Title Page

U/BL 5.00 - User Guide

Documentation Revision 5.00.0014

Transoft Web-site

Help on Help

Document Feedback

Copyright © 1991-2004 Transoft Limited - All rights reserved


Introduction

U/BL is an integrated family of products that provides the flexibility you need in a modern software development environment. U/BL gives you the product range, functionality and portability to develop effective software solutions for real business needs using modern GUI, client/server, and database technologies.

U/BL is an integrated product set that meets your requirements for modern GUI, client/server computing. It comprises:

  • The U/BL language, which is compatible with Data General and Bluebird SuperDOS Business Basics

  • The Universal Graphical Interface (U/Gi), which is an enhanced Windows terminal emulator, giving your applications a Windows look and feel

  • Embedded U/SQL Report Writer. This is a query language, which allows users to retrieve information from a variety of file and database structures.

Note:

  • The functionality documented assumes you are running U/BL 2.20+ and U/GI 4.0+. Using earlier versions of these products will limit the functionality available.

  • The U/BL On-line Help is currently in development, and so is in an incomplete state.


U/BL Under Windows

U/BL under Windows uses a client-server process model. Specifically, while running U/BL there is a U/BL process which runs on the server machine (Windows 2000, Windows NT or Windows 95/98), and a U/Gi client process running on the end-user's machine (this can be a remote workstation or the server machine itself).

There are two process models for U/BL under Windows:

  • Single Tier

  • Multi-Tier

In the single tier model the U/BL server and the U/Gi client both run on the server machine.

In the multi-tier model the U/BL Server runs on the server machine, while the U/Gi client runs on a Windows NT or Windows 2000 workstation or Windows 95/98 machine which is connected to the server machine across a TCP/IP network.

With both these models, all communication between the client (U/Gi) and server (U/BL) is made via a TCP/IP network.

Preparing to run U/BL

In order to run U/BL under Windows, a user-account has to be created for each person who is allowed to run U/BL.

U/BL users under Windows NT and Windows 2000

When running under Windows NT or Windows 2000, U/BL utilizes the Windows NT or Windows 2000 user accounts, therefore it is necessary for each U/BL user to have an account. These accounts do not need to be specific to individuals (accounts for specific types of users can be employed, for instance 'sales' or 'dispatch'). All U/BL users should be created using the U/BL Administrator utility (see next section). If a Windows NT or Windows 2000 account already exists for the user, the U/BL Administrator merely sets-up the U/BL specific details but if the user does not already exist, the U/BL Administrator creates the necessary account prior to recording the U/BL details.

U/BL users under Windows 95/98

Under Windows 95/98, there is no operating system support for user-based security so the concept of U/BL users is purely an administrative aspect of U/BL rather than an integrated part of the operating system. This means that on Windows 95/98 it is only necessary to create a record of the user's details for use by the U/BL run-time. This is achieved by adding a U/BL user using the U/BL Administrator utility (see next section).

U/BL Administrators

In order to prevent a U/BL user from having the ability to terminate or interrupt U/BL jobs with UBLMON, this utility is protected by an additional level of security. Only U/BL users who have been given U/BL administration rights can run UBLMON. These rights can be granted to an existing U/BL user by ticking the 'Give Administrator Rights' checkbox when editing the user's details using the U/BL Administrator (see next section).

Note: This administrator right is solely U/BL based, and is not related to the Windows NT or Windows 2000 administrator rights.

Selecting file exclusion algorithms

U/BL under Windows uses psuedo-inodes to implement file exclusion. These rely on hashing the full UNC pathname of a file into a single 32-bit number. These cannot be guaranteed to be unique, so several algorithms are provided which can be used if necessary. If a failure does occur it will fail safe, so corruption should not result.

Once you have installed the Business BASIC data files run the picheck program in the ubl/bin directory to determine the correct hashing algorithm to use for your system. This utility checks that no files collide, and attempts alternative algorithms if they do.


U/BL Administrator

The U/BL Administrator utility allows U/BL user accounts to be created, deleted and manipulated. To start the utility click the U/BL Administrator shortcut on the Windows Task Bar Start menu:

The U/BL Administrator dialog box is displayed:

This allows the user to:

  • ADD a new U/BL user

  • Remove (DEL) a user from the list of U/BL users

  • Modify (EDIT) the configuration of an existing U/BL user

The Options button displays a dialog box which allows the user to change how user names are displayed within U/BL.

User names can be displayed in one of the following formats:

  • User Name

  • Full Name

  • User Name (Full Name)

  • Full Name (User Name)

If a user has no full name specified, only the user name is shown. Existing Windows 95/98 users do not have a full name specified, but this may be specified from the User Details button on the User Details dialog box.

Selecting the Add User by name (not from list) check box allows you to add users by entering the user name rather than by selecting from a list of users. This can be useful when adding users on large networks.

Under Windows NT or Windows 2000 the Options dialog box also allows user validation to be performed in a different domain, than the one on the machine running the U/BL server. Entering a domain name in the Authentication Domain edit box, ensures user logins are validated by that domain rather than by the local machine.

Note: When changing between using local or domain based authentication existing user accounts must be recreated. Additionally this option requires that the user is a Domain Administrator on the remote domain.

Adding a new U/BL user

To add a new U/BL user click the ADD button. Under Windows NT the Set up User for U/BL dialog is displayed showing a list of existing users:

To add one of these to the list of U/BL users, highlight that user and press OK.

Under Windows 95/98 there is no concept of operating system user accounts so this stage is bypassed and the utility prompts for the user-details. Under Windows NT or Windows 2000, you must first click the Create New User button to display the user-details dialog box:

Once this dialog box is displayed, you can enter the new user's details. Click the OK button to create that U/BL user (under Windows NT or Windows 2000 this also creates the user under the operating system).

Removing a user from the list of U/BL users

To remove a U/BL user, simply highlight that user's name in the list of U/BL users and click the DEL (delete-user) button. This removes the user from the group of U/BL users.

Note: Under Windows NT or Windows 2000, this function does NOT remove the user's operating system account.

Modifying the configuration of an existing U/BL user

To modify the user's details, highlight the user's name and click the EDIT button. The U/BL user details for: <User name> dialog box is displayed:

This allows you to modify a user's home directory, U/BL administrator privileges and environment settings.

It is often useful to specify one 'template' user and copy their settings for all subsequent users. This may be achieved by selecting the Same as option in the User Details dialog box. Specifying this disables changes to the environment for this user, and instead allows selection of a user whose environment this user will clone.

To change the user's password, full name, or description the 'User Details' button from the U/BL Administrator's 'Edit details for user' screen must be used under Windows 95/98. To achieve this under Windows NT, use the Windows NT 'User Manager' or under Windows 2000, the 'Local Users and Groups' management snap-in.

Note: While the registration of the U/BL users is carried out by storing their details in the registry, Transoft suggest in the strongest possible terms that this information is not modified by the Windows Registry Editor. The administration of the U/BL user accounts must always be carried out via the U/BL Administrator utility.


U/BL Control Panel

To start the U/BL Control Panel run the U/BL Server shortcut in the Windows' control panel group (on the machine where the U/BL server-software was installed). The U/BL Control Panel property sheet is displayed:

This is comprised of the following property pages:

  • Server

  • Environment

  • Serial

  • Obituary and Logging.

Server

The Server property page is displayed by default (see above). It contains the following fields:

Server state

Start

Stop

The start and stop buttons are used to manually start or stop the U/BL run-time when implemented as a system service.

To start the U/BL Server click the Start button. The traffic light will change from red to green to indicate that the U/BL Server has started:

To stop the U/BL Server click the Stop button. The traffic light will change from green to red to indicate that the U/BL Server has stopped.

To pause the U/BL Server click the Pause button. If the Server is paused, U/BL sessions that are currently running will continue to run but it will not be possible for new U/BL sessions to be started unless the user has Administrator rights.

TCP/IP Settings

Port number

Specifies the TCP/IP port number to use for U/BL.

Sever settings

Banner

Specifies the location of the U/BL banner file.

Script

Specifies any start-up script that is to be run when the U/BL run-time service is started, for instance, to start-up any background U/BL jobs.

BBENV

Specifies the location of the default BBENV.

The U/BL Control Panel allows the administrator to:

  • Specify whether the default user environment can be over-ridden by the individual U/BL users

Note: When a user-process model for the run-time is in use, the starting and stopping of the run-time should be performed from the instance of UBLMON which is behaving as the server process. The Control Panel's start/stop run-time functionality is only available when the run-time is being implemented via a system service.

Environment

Click on the Environment tab to display the Environment property page:

This property page allows you to add and remove user environment variables.

To add an environment variable:

  1. Click the ADD button

  2. Enter the name of the environment variable in the Variable field

  3. Enter the value in the Value field.

  4. Press RETURN

Te delete an environment variable highlight the variable and click the DEL key.

To allow user-specific environments to over-ride the global environment check the Allow users to override these settings box.

Obituary an Logging

Click on the Obituary and Logging tab to display the Obituary and Logging property page:

It contains the following fields:

Obituary
Check every | Specifies how frequently any obituary process checks the U/BL run-time.
Log obituary to | Specifies whether U/BL's obituary function is logged and to which file.
Start with runtime | Specifies whether or not the U/BL obituary function is run in parallel to the U/BL run-time.
Verbose logging |
Logging
Log system calls |
Log U/BL Server to | Specifies whether the operations of the U/BL server are logged, and if so to which file
Log U/BL to | Specifies whether U/BL's operations are logged and to which file.

Specify the default user environment to for users logging into U/BL.


U/BL Environment

Like all versions of U/BL, the environment that the U/BL jobs are run in has a great effect on the operation of the software. Also, as under other platforms, Windows offers user-specific and global environmental characteristics. The difference between the traditional operating systems and the Windows operating environment is that there is no operating system shell where the environment variables can be manipulated. For this reason, the configuration of U/BL's environment differs significantly to the more traditional platforms.

The global U/BL environment

The global U/BL environment is the configuration that all U/BL jobs inherit. It can optionally be over-ridden by the individual users' settings and configures the U/BL server process.

There are two methods of adding items to the global U/BL environment:

  1. The most straightforward method is to define a global BBENV file and make the settings in this file.

  2. The alternative is to define the global environment settings via the Environment property page of the U/BL Control Panel.

Note: New settings are only detected when the U/BL run-time is re-started.

The user-specific U/BL environment

It is possible to maintain user-specific environment settings with U/BL for Windows. These can optionally over-ride the global settings (see previous section).

To control which type of environment setting takes precedence over the other, use the Allow users to override these settings check box on the Environment property page on the U/BL Control Panel. To define user-specific environment settings, use the U/BL Administrator utility and double click on the name of the user whose environment you wish to change:

To edit an existing environment setting, either double click on the relevant variable in the list, or highlight the variable and click the EDIT button. To create a new variable, click the ADD button and enter the name and value of the environment variable in the Add an environment variable dialog box, and click OK.

To delete a variable, highlight it and click the DEL button.

The client-specific U/BL environment

A third method of specifying the run-time environment for U/BL is available via U/Gi itself. Once again, the priority of settings made in this manner depends on the Allow users to override these settings check box on the Environment property page on the U/BL Control Panel. This method allows the user to specify their own supplemental environment settings in a file defined on U/Gi's command line. This is achieved by using the following command line switch when invoking U/Gi:

-e<EnvFile>

For example:

c:\ugi\ugi.exe -ec:\my_dir\my_env

transfers the specified environment settings file from the client PC to the server and the U/BL job bases its environment on the contents of the file in addition to the existing environment.

This switch allows the user to specify an environment file, which exists on the client machine. The environment variables defined in this file are used to supplement the globally defined settings (either from the global BBENV or the global environment) and the user's environment definition. When U/Gi connects to U/BL under Windows this file is silently transferred to the server and its contents supplement any other user-specific environment variables.

Summary of priority of environment variables

The relative priorities of the global; user; and client-specific environments are determined by the Allow users to override these settings check box on the Environment property page of the U/BL Control Panel.

If this is not selected, the precedence is:

If the user settings are allowed to override the global ones the precedence is:

The BBENV file used is always determined by the highest priority setting of the BBENV environment variable (either user-specific or global definition dependant on the 'take priority' switch).

For example, the following environments:

Global Environment | Client-specific Environment | User-specific Environment
BBVAR1=GLOBAL_VALUE | BBVAR1=CLIENT_VALUE | BBVAR1=USER_VALUE
BBVAR2=GLOBAL_VALUE | BBVAR2=CLIENT_VALUE |
BBVAR3=GLOBAL_VALUE |  | BBVAR3=USER_VALUE
 | BBVAR4=CLIENT_VALUE | BBVAR4=USER_VALUE
 |  | BBVAR5=USER_VALUE
 | BBVAR6=CLIENT_VALUE |
BBVAR7=GLOBAL_VALUE |  |
BBENV=GLOBAL_BBENV | BBENV=CLIENT_BBENV | BBENV=USER_BBENV

is seen in U/BL as:

Override not allowed | User-override allowed
BBVAR1=GLOBAL_VALUE | BBVAR1=CLIENT_VALUE
BBVAR2=GLOBAL_VALUE | BBVAR2=CLIENT_VALUE
BBVAR3=GLOBAL_VALUE | BBVAR3=USER_VALUE
BBVAR4=CLIENT_VALUE | BBVAR4=CLIENT_VALUE
BBVAR5=USER_VALUE | BBVAR5=USER_VALUE
BBVAR6=CLIENT_VALUE | BBVAR6=CLIENT_VALUE
BBVAR7=GLOBAL_VALUE | BBVAR7=GLOBAL_VALUE
BBENV=GLOBAL_BBENV | BBENV=CLIENT_BBENV

Only those environment variables in the BBENV, which are not also set in any of the global, client specific or user specific environments, are used by U/BL. For example, in the above case BBVAR1-7 are never taken from the BBENV.


The U/BL Runtime

U/BL Run-time

The U/BL run-time differs depending on wether you are running on the Windows 2000 or Windows NT, or the Windows 95/98 operating environments:

  • The U/BL run-time under Windows 2000 or Windows NT

  • The U/BL run-time under Windows 95/98.

  • Limitations of running the U/BL run-time under Windows.

Under Windows 2000 or Windows NT

There are two methods of implementing the U/BL run-time:

  • As an system service

  • As a user process.

The U/BL run-time implemented as a system service

By default under Windows NT or Windows 2000 the U/BL run-time and server process is provided as a system service (a background process running in the system account).

The main advantages of this implementation are that the U/BL run-time is automatically started whenever the server is re-booted and that the system service does not have to be stopped if another Windows NT or Windows 2000 user wants to log on to the server machine. As this is the default manner of operation when U/BL is installed, the UBLMON shortcut (program item) is created with '-H localhost' as part of the command line. This tells UBLMON that the run-time is running on the local machine and that (as the '-S' switch is not specified) the UBLMON process will not act as the U/BL server (in other words, the server is to be provided by a system service).

When running U/BL in this mode, control over starting and stopping the U/BL run-time can be achieved via either the U/BL control panel (see below) or natively from the Windows NT or Windows 2000 system services control facilities (refer to your operating system documentation). In this mode, the only control offered by UBLMON is over individual U/BL jobs, UBLMON cannot be used to start or stop the U/BL run-time service.

The U/BL run-time implemented as a user process

Implementing the U/BL run-time as a user process, is the same method used when running U/BL under Windows 95/98. This means that whenever the U/BL run-time exists, a task is running on the Windows NT or Windows 2000 server to provide U/BL's run-time services. There are several steps involved in setting up a Windows NT or Windows 2000 machine to use a process-based run-time:

  1. The first step is to stop the run-time service as this is the default method of implementing the run-time under Windows NT or Windows 2000. This can be done by using the U/BL Control Panel, but this only stops the currently running service. If the machine is re-booted, the U/BL run-time service is automatically restarted when Windows re-boots. To prevent this and stop the service permanently the automatic start-up facility must be disabled using Windows' system services control facilities. Refer to your Windows documentation.

  2. The UBLMON program (see UBLMON section) now needs to be told that the run-time is to be started as a user-process. This is achieved by adding the '-S' (server) switch to the UBLMON command line arguments in place of the existing '-H localhost' (look for the run-time service on the 'localhost' machine) entry. This is achieved by modifying the shortcut for UBLMON in the usual manner (refer to your Windows NT or Windows 2000 documentation). If UBLMON is also started with the optional '-T' switch, then it operates in tray mode (places UBLMON in the system tray).

However as Windows NT and Windows 2000 implement a rigid user authentication environment, there are a couple of security issues which apply under this method of implementing the run-time.

  1. The first of these is that the UBLMON process which provides the U/BL run-time must always be started by a user with Administrator rights (see your Windows NT and Windows 2000 documentation).

  2. The Administrator group also needs to possess some rights, which are not normally granted in the default configuration of Windows NT and Windows 2000. UBLMON prompts for the rights it requires, the first time it is run in server mode.

These rights are:

Act as part of the operating system,

Increase quotas, and

Replace a process level token.

They are needed for the server to create processes in the name of non-interactively logged on users. When this happens, simply select OK for these rights to be added to the Administrator Group. You have to then log on again as administrator for the changes to take effect.

The U/BL run-time under Windows 95/98

Under Windows 95/98 the U/BL run-time is implemented via a user process. This means that whenever the U/BL run-time exists, a task is running on the Windows 95/98 machine acting as the server process.

This task is an instance of UBLMON and must not be terminated. This copy of UBLMON will have been started with the '-S' (server) and '-T' (tray) switches, which is the default setting on the shortcut when U/BL has been installed under Windows 95/98.

As well as providing the U/BL run-time, the process can also be used as a normal instance of UBLMON to control and interrogate the run-time. This is the only instance of UBLMON which can start or stop the run-time, but other remote copies of UBLMON may report on or signal the U/BL jobs once the run-time has been started.

Limitations of running the U/BL run-time under Windows

UBLMON's table configuration switches

The UBLMON command line switches for configuring the size of the U/BL run-time's tables ('-L', '-J', etc.) are not supported in U/BL for Windows.

The equivalent environment variables (BBNLOCKS, BBNFILES etc.) are however, fully supported and these should be employed should this functionality be required.

Running UBLMON from the command line

The ability to run UBLMON or specify the banner file from the command line is not supported in U/BL for Windows.

Using UBLMON to start and stop the run-time

The functionality of UBLMON starting and stopping the run-time is only available under Windows when the program is operating as the run-time server process itself (UBLMON was started using the -S switch). A remote instance of UBLMON (whether or not it is running on the server machine where the U/BL run-time is installed) cannot start or stop the run-time implemented by another UBLMON process or a system service.

When running on Windows NT or Windows 2000 with the run-time implemented as a system service, either use the U/BL Control Panel or the Windows system services control facilities to stop and start the U/BL run-time.


U/BL Monitor Utility

The U/BL monitor utility UBLMON, provides a means of controlling and interrogating the U/BL run-time. This utility is an administration facility for the U/BL session and can be run either on the server machine or from a remote workstation. In addition, when the U/BL run-time is implemented using the user-process model one instance of UBLMON also acts as the U/BL server process. The operation of UBLMON under Windows is broadly similar to the other platforms that support U/BL with the exception that the U/BL run-time cannot be started automatically by the first U/BL job that is executed. In addition, remote instances of UBLMON cannot be used to start or stop the run-time.

To start UBLMON, click the U/BL Monitor shortcut on the Windows Task Bar Start menu:

The U/BL Monitor dialog box is displayed:

Command line arguments

The operation of the UBLMON utility can be modified by specifying command line switches in the shortcut that starts the process:

-H <Servername>

Tells UBLMON to run as a client of the run-time running on the specified Host. For implementations of the U/BL run-time running as an NT service the shortcut which starts UBLMON on the server, will specify -H localhost indicating the run-time is running (or to be run) on the local machine. For remote instances of UBLMON (under Windows), the specified '<Servername>' is that of the machine on which the U/BL server process is running.

Tells UBLMON to run as a client of the run-time running on the specified Host. For implementations of the U/BL run-time running as an NT service the shortcut which starts UBLMON on the server, will specify -H localhost indicating the run-time is running (or to be run) on the local machine. For remote instances of UBLMON (under Windows), the specified '<Servername>' is that of the machine on which the U/BL server process is running.

-P <Port>

Tells UBLMON which TCP/IP Port that the U/BL server process is running/should be run on. This facility is provided should the default TCP/IP port that U/BL uses (port 23) be in use by another application. This switch must be used along with the corresponding U/Gi -P switch (see U/Gi's release notice).

-S

Tells UBLMON to act as the U/BL Server process once the U/BL run-time has been started. When running in this configuration (with the U/BL run-time provided by a user-process) terminating the UBLMON process removes the U/BL run-time.

-T

Selects Tray mode. This places UBLMON in the system tray.

-r<sec>

Specifying the -r switch changes the refresh rate of the FILES/LOCKS/JOBS view in the monitor. The default is 10 seconds. If these tables increase in size and take several seconds to refresh, then the refresh rate should be increased, otherwise the monitor would be constantly updating (with the "busy" pointer displayed).

-m

This -m switch plcaes a Refresh button on the bottom of the screen (see figure above) to manually refresh the screen and disables the automatic refresh.

However, if the -r switch is also specified, then the UBLMON table is refreshed both automatically and manually.

UBLMON restrictions

  • The UBLMON command line switches for configuring the size of the U/BL run-time's tables (-L, -J) are not supported under Windows. The equivalent environment variables (BBNLOCKS, BBNFILES) are however, fully supported and these must be employed if this functionality is required.

  • The ability to run UBLMON or specify the banner file from the command line is not supported in U/BL for Windows.

  • A further limitation of the Windows version of UBLMON is that it is not possible to specify UBLMON commands, or the value of BBSIGNON on the command line.

  • A remote instance of UBLMON cannot start or stop the U/BL run-time. This includes an instance of UBLMON interrogating a U/BL run-time implemented by a system service under Windows NT or Windows 2000, even if the UBLMON process is running on the server machine.

  • The functionality of UBLMON starting and stopping the run-time is only available under Windows when the program is operating as the run-time server process itself (UBLMON was started using the -S switch). A remote instance of UBLMON (whether or not it is running on the server machine where the U/BL run-time is installed) cannot start or stop the run-time implemented by another UBLMON process or a system service.

  • When running on Windows NT or Windows 2000 with the run-time implemented as a system service, either use the U/BL Control Panel or the Windows system services control facilities to stop and start the U/BL run-time.


U/BL Obituary Function

The U/BL obituary function operates in the background and keeps track of the status of the U/BL run-time tables, periodically cleaning them up as necessary. The obituary function is in fact a separate thread (single path of execution) of the U/BL server, hence it is not a separate executable as under UNIX.

The obituary function is controlled by the Obituary and Logging property page of the U/BL Control Panel. It is used to select whether the process is started automatically when the U/BL run-time is created. The operation of the obituary function can in addition be automatically logged to a disk file.


Foreground U/BL Jobs

Basic concepts

Under Windows, the process model of foreground U/BL jobs follows a client-server architecture. Specifically, while running U/BL there is a U/BL process which runs on the server machine (Windows), and a U/Gi client process running on the end-user's machine (this can be a remote workstation or the server machine itself).

Additionally, the Windows version of U/BL has a more complicated run-time than UNIX versions of U/BL. For instance, the U/BL run-time is not just restricted to the shared run-time tables, but also includes a dispatcher process. This listens for connecting U/Gi tasks, verifies their logon procedure (validates the username and password) and starts up the U/BL process for that connection.

The term run-time is used when referring to U/BL for Windows, to encompass both the more familiar run-time tables (as displayed by UBLMON) and the U/BL dispatcher process.

Manual login

To run U/BL, first ensure that the U/BL run-time has been started correctly. Ensure that the U/Gi software has been installed correctly and been configured to attach to the correct host.

Start the U/Gi session and open the previously defined connection to automatically bring up the U/BL Login dialog box:

Running U/BL from a client PC which has U/Gi installed, requires a suitable connection to be created. See the Installing U/Gi section.

Logging in with a valid user name and password starts a U/BL session.

Automated login

It is possible for the system administrator (or the end-user) to automate the login process when starting U/BL, by pre-selecting the username and/or password. This is achieved by passing the information to U/Gi in the form of command line switches. To specify the username U/Gi is to use when logging on, add the switch -U <Username> to U/Gi's shortcut/program item. This causes U/Gi to prime the first line of the login dialog box with the specified username when it attaches to the U/BL server. To specify the password U/Gi is to use, add the switch -X <Password> which primes the password field with the specified item.

Specifying both a valid username and password in this manner, results in the login dialog box being automatically appended, logging the user in.

Specifying a program to RUN

Under the Windows implementation of U/BL, it is not possible to type 'UBL Progname' to automatically start a program when a foreground U/BL job starts. This is because U/BL itself is never directly started by the user, it is started by U/Gi via the U/BL dispatcher process.

To allow a foreground U/BL job to automatically RUN a specified program as soon as it starts, a new command line switch has been added to U/Gi. If -R progname is added to the U/Gi command line, the specified program (progname) is run once U/BL has started.

Alternatively, the new environment variable UBLNTPROG may be used. This allows the definition of the program to be made on a global or per user basis, when U/BL starts (dependent on whether the variable is defined in the global or in the individual users' environment). The precedence between these two methods of specifying the program to run, is determined by the Allow users to override these settings check box on the Environment property page of the U/BL Control Panel. If this is set, the '-R' switch takes priority, otherwise the global environment variable is used.


Background U/BL Jobs

Basic concepts

As under other versions of U/BL, it is possible to run the Windows version of U/BL as a background job. Running in this mode the process model employed is not a client-server model.

As under UNIX implementations of U/BL, any background job is run solely on the server machine. All background tasks are run with their screen output directed to a disk file, which must reside on the server machine. Similarly, they take their keyed input from a disk file, which must also be located on the server. There are three methods of starting U/BL background jobs under Windows:

  • Manually

  • Automatically when the U/BL run-time is started

  • Via the STME 19 or $EXECUTE commands from an existing U/BL job.

Manually starting background U/BL jobs

Using this method to start background U/BL jobs, the tasks are started under an MS/DOS session (the 'Command Prompt' under Windows NT or Windows 2000 or the 'MS/DOS Prompt' under Windows 95/98) running on the server. This means that this method of starting U/BL jobs can only be used from the system console.

Having started an MS/DOS session on the server, background U/BL jobs can be started either directly from the command line or via a batch file. Either way, there are two methods of starting the tasks:

  • The U/BL jobs can either be created and left to run on their own (with control returning to the starting DOS session immediately). The command for starting off a U/BL job and continuing processing without waiting for completion of the job depends on the operating system in use. Under Windows NT or Windows 2000, use the following command:

start /b c:ubl\bin\ubl <infile >outfile ublprog

Under Windows 95/98, the command is:

command /k c:ubl\bin\ubl <infile >outfile ublprog

  • The U/BL jobs can be run to completion before control is returned to the starting process. The command for waiting on completion of the U/BL job is the same under both Windows NT or Windows 2000 and Windows 95/98:

c:\ubl\bin\ubl <infile >outfile ublprog

When starting U/BL background jobs it is always a good idea to include the full pathname of both the input infile and output outfile files, so that there is no confusion over which file U/BL will use. You must ensure the infile actually exists and, for technical reasons the null device file, 'NUL' cannot be used to provide the input stream. You can, however, create an empty file using notepad or a similar text editor. The output file, outfile need not already exist as this is created when it is required. If you do not wish to retain the screen output of the process, you may direct the output to the null device ('NUL'). As under other platforms' implementations of U/BL, the redirected output receives the banner display.

As this process is carried out once a user has logged onto the Windows machine, jobs started in this manner inherit that user's environment. Only those drive mappings or environment variables defined at the command prompt is available to the U/BL process. All of the necessary environment variable settings for the background tasks must be set at the command prompt prior to running U/BL (or at the start of any batch file in use).

Note: As the global (as set by the U/BL Control Panel's Environment property page) and the user-specific (as set by the U/BL Administrator's User details dialog) U/BL environment settings are only read by the U/BL dispatcher process, these will not be available to manually-started U/BL background tasks.

The major disadvantage of starting background jobs under a user account is that the jobs are terminated if the user logs off the server.

Automatically starting background U/BL jobs

It is possible to automatically start U/BL background jobs via a batch file, which is executed when the U/BL run-time is started. The commands in the batch file to start U/BL are the same as those for manually started background tasks (see above). However, as the automatically started jobs are run in the same environment as the U/BL run-time, you must ensure that this environment actually contains the correct settings to allow the job to run. It is best to assume that any drive mappings or environment settings associated with a particular user will not exist (unless the U/BL run-time has been started in the particular account in question).

The only U/BL environment settings that are read by any automatically-started background jobs are those defined in the environment of the process starting the job (the start-up batch file), and the global U/BL environment. The batch file for starting the background U/BL jobs must therefore explicitly set up the environment each job requires.

Note: The user-specific (as set by the U/BL Administrator) U/BL environment settings are not available to automatically started background tasks, as they do not run in the name of a specific user.

Specify the full path of the batch file in the Script field of the Server property page of the U/BL Control Panel. Once this has been done, whenever the U/BL run-time is started, the batch file will be used to start up the U/BL background tasks. Using this method allows U/BL jobs to be automatically started when the U/BL run-time is created, and is therefore an ideal method of installing shared procedures.

Additionally, under Windows NT or Windows 2000 (should the U/BL run-time be implemented as a system service) this method has the advantage that background jobs will be unaffected by users logging off from the system console. However, under Windows 95/98 (or under Windows NT or Windows 2000 if the run-time is not running as a system service) since the U/BL run-time is a user process, if the user on the server machine logs off, all the U/BL jobs (not just the background ones) are terminated.

Two example batch files are provided in the U/BL release; one for Windows NT or Windows 2000 and one for Windows 95/98. This is because the command to start a fully detached background job differs on these two operating systems. These two scripts show typical command lines for starting off a job to install the shared procedures (where processing of the batch file is suspended while this job is running) and for starting off a fully detached background job (where the batch file just starts up the job and does not wait for it to finish). Both of these scripts have all the commands commented out so that when the batch file is run, nothing happens. This is because the installation of U/BL sets up the correct script (for Windows 2000, Windows NT or Windows 95/98) as the start-up script to be run when the U/BL run-time is started. To configure your own start-up script, find the name of the 'skeleton' script by referencing the U/BL Control Panel and edit this to include commands to fire up your background tasks (using the examples as a guide).

Starting background U/BL jobs from U/BL itself

U/BL itself can be used to launch background U/BL tasks using the STME 19 or $EXECUTE statements. This is achieved in much the same way as under other versions of U/BL:

$EXECUTE "c:\ubl\bin\ubl <infile >outfile ublprog &",ER

if you want to start off the background task and continue running in your foreground task, or:

$EXECUTE "c:\ubl\bin\ubl <infile >outfile ublprog",ER

if you want to wait on termination of the background task. If you are redirecting either the standard input or the standard output then you must redirect them both. As when starting background tasks under the command prompt, it is a good idea to include the full pathnames of the input and output files (also remember that the input file must exist and cannot be the null device, 'NUL').

Background U/BL tasks started from a foreground task inherit much of the environment of the task from which they are started. Explicitly, a background U/BL task started in this manner picks up the environment variables that were set when the foreground task started (the global and user specific settings) and will inherit the same drive mappings as seen by the foreground job. However, any environment settings made via a $PUTENV in the foreground task are not reflected in the background process.

Restrictions

When U/BL is installed on Windows NT, the screen saver on the console of the server machine does not work when U/BL is running.

This problem can usually be resolved by using the UBLNTLOCKWORKTOP environment variable, but this does not work on all of the older NT service packs. Microsoft outlines an alternative solution to overcoming these errors. Refer to the Microsoft Knowledge Base article, Q142676, Overcoming Usr32.dll Initialization failure errors.


Differences between Windows and UNIX implementation of U/BL

The following issues are all the known differences between the Windows and the UNIX implementation of U/BL. New concepts of operation imposed on U/BL by the Windows environment are also described.

Some of the limitations imposed by the operating system environment cannot be resolved; other issues are merely deficiencies with the current version of the product and will be resolved in a later release.

The issues can be categorized into the following sections:

  • File handling

  • Printer handling

  • Communications

  • Miscellaneous.

File handling

'File in use' errors

U/BL under Windows uses psuedo-inodes to implement file exclusion. These rely on hashing the full UNC pathname of a file into a single 32-bit number. These cannot be guaranteed to be unique, so several algorithms are provided which can be used if necessary. If a failure does occur it will fail safe, so corruption should not result.

The correct algorithm to use for your system can be determined by running the picheck program in the ubl/bin directory. This checks that no files collide, and attempt alternative algorithms if they do.

Case sensitivity

File names (including U/BL programs and data files) under Windows are not case sensitive, for example, 'BBENV' is equivalent to 'bbenv'.

Embedded spaces

U/BL for Windows cannot currently cope with file paths that include the space character. This limitation may be resolved in a future release.

Long filenames

U/BL supports Windows long filenames (outside of the 8.3 format), but problems may be encountered with files that were previously held on a file server that could not cope with long file names. Names will have been truncated to the DOS 8.3 standard, but will still be referred to in the Business Basic program by their long filenames, so Windows NT or Windows 2000 will not be able to retrieve them. The long-term solution is to rename the files back to their full filenames; for the short term, setting the environment variable BBPATCH=1 relieves many of these problems.

Note: U/BL only supports pathnames of up to 64 characters in length.

MTDIO tape support

There is no tape support, and we have no plans for this at present.

Network resources

Under Windows, network resources (printers, shared drives etc.) are made available over the network via ‘shares’. In the case of shared directories, drives or files, these resources can be accessed either via their Universal Naming Convention (UNC) pathname (see below) or via drive mappings to the share.

For example, if there is a file, ‘A_FILE’ on the C drive of a machine ‘A_PC’, and that machine has exported its C drive as a share, ‘C_DRIVE’; then the file can be referenced on another machine by its UNC path ‘\\A_PC\C_DRIVE\A_FILE’. Alternatively, the remote machine can set up its own drive mapping and use that (the remote machine could assign the drive ‘M:’ to the path ‘\\A_PC\C_DRIVE’ and address the file as ‘M:\A_FILE’). Both of these methods are available under U/BL.

If the file is addressed via its UNC path, the success of the attempted access is determined by whether or not the user attempting the operation has permissions to access the file and the share (assuming that the machine on which the file resides does not stop sharing the C drive). If the attempt is made via a mapped drive, its success is still be governed by the user’s permissions against the file but it also depends on that user ‘seeing’ the drive mapping. Under Windows, drive mappings are set up on a per-user basis. Each Windows user has their own set of drive mappings which are set-up when they log into Windows.

Therefore in order for a U/BL job to be able to access our example file, the user running U/BL needs permissions to access the file and U/BL needs to be able to ‘see’ any drive mapping used. However, when users log in to U/BL, U/BL does not log them into Windows (they will already be logged into Windows on their local, client PC but U/BL does not log them into the server machine). This means that the user’s drive mappings are not set up for the U/BL process. In fact, the only drive mappings that the U/BL job can see are those that it inherits from its parent U/BL server process.

The U/BL server process (either the U/BL run-time service or UBLMON running in server mode) inherits its mapped drives from the account it is running in. Under Windows 95/98/Me (or under Windows NT or Windows 2000 if the U/BL run-time is not running as a service) this means that the mapped drives available to U/BL are those available to the user who started the run-time. For Windows NT or Windows 2000 when the U/BL run-time is running as a system service, the drive mappings available to U/BL are those available to the account that the run-time service is being run in.

In order to make particular drive mappings available to U/BL, the drive mapping must therefore be available to the user who started the U/BL run-time (Windows 95/98/Me or if the run-time isn’t being implemented as a system service Windows NT or Windows 2000) or to the account that the U/BL run-time service is running in.

By default, the U/BL run-time service under Windows NT and Windows 2000 is run in the ‘System Account’. This account has no drive mappings of its own and tends to pick up drive mappings from the user who is interactively logged on to the system console.

If you want to use drive mappings, it is therefore wise to run the run-time service in an account, which you can guarantee, has the drive mappings you require. To change the account, in which the U/BL run-time service is run on Windows NT use the services applet on the Windows Control Panel. Under Windows 2000, right-click on My Computer, select the Manage option, expand the Services and Applications section of the tree view and select the Services option. For either operating system, double-click the U/BL Server 2 entry in the displayed list of services. To make the U/BL run-time service execute in a Windows user account, select the This Account radio button and enter the name and password of the account you wish to run the service (for Windows 2000 this radio button is found on the separate Log On tab of the Service Properties dialog). You may find it easier to create a special account on the network rather than use a ‘real’ user’s account. The user must however have the following rights:

Act as part of the operating system,

Increase quotas, and

Replace a process level token.

This process makes the mapped drives of the selected user available for use under U/BL.

Note: Each U/BL user must also have individual access rights to the mapped drive, as files are created in that U/BL user’s name.

Refer to your Windows documentation as necessary.

Besides controlling which set of drive mappings are used by U/BL, starting the run-time service under a specific user account has been found to improve permission problems when accessing network resources. If you are experiencing problems accessing network resources, particularly if the problems are effected by who is logged on to the system console, Transoft suggest that you try running the U/BL service in a specific user account.

Path separators

Like the operating system, U/BL supports both forward and backward path separators ‘/’ and ‘\’ under Windows NT and Windows 2000. However a combination of the two cannot be used in the same path. It is therefore recommended that the DOS style ‘\’ is used, particularly as Windows 95/98 and U/Gi do not support forward ‘/’ separators.

UNC path names

U/BL for Windows supports UNC (Universal Naming Convention) path names. UNC path names are a network-wide method of file identification to prevent problems where the same file is mapped onto different drives. The format of a UNC name is:

\\<Computer Name>\<Share name>\<path on share>

Thus the file c:\tmp\test.txt on computer SERVER is accessed as:

\\SERVER\C_DRIVE\tmp\test.tx.

If the C drive of that machine has been exported as the share named C_DRIVE.

Files in the file table are referenced by pseudo-inodes based on the UNC path name, and so access to files on mapped drives is permitted.

Under Windows NT, the default operation of the operating system is to prevent the access of local drive mappings via UNC paths. This security restriction may be removed by a Windows registry setting; refer to the Microsoft Knowledge Base article Q122702.

Printer handling

There are two basic methods of accessing a network printer under U/BL:

  • The printer can be accessed via U/BL’s spooling mechanism, or

  • The printer can be opened directly.

Both methods require the user to have access to the requisite network printer. This depends on the permissions the user has with regard to that resource and whether or not U/BL can actually see the resource over the network. For details on accessing network resources from U/BL see the section above.

Accessing a printer via U/BL’s spooling mechanism

U/BL’s print spooling mechanism is selected via the environment variables BBSPOOL and, optionally, BBPTYPE. When U/BL’s spooling mechanism is in use, opening a printer (either a file listed as a printer in the BBPTYPE file or a filename starting with a $ or @ symbol) causes a temporary file to be created (in the directory pointed to by BBTMP). All output destined for the printer is directed to this file until the printer is closed.

On closing the printer, the temporary spool file is also closed. The BBSPOOL macro is then called with the pathname of the temporary spool file, in order to send the data to the printer. Under Windows, the contents of the BBSPOOL batch file should contain a command to send the temporary spool file to the target printer, for example:

COPY %1 \\MACHINE\PRINTER

While the U/BL job never actually opens the device, the user must still have access rights to the resource as the BBSPOOL macro is called in that user’s name.

Accessing a printer directly

This can be achieved by either OPENing the device’s UNC path, for example:

OPEN FILE[CH,M],”\\MACHINE\PRINTER”

or by opening the physical port that the printer is connected to (or the port which is captured to the printer).

For example:

OPEN FILE[CH,M],”LPT1”

When running on Windows 95/98, you may experience problems accessing the printer via its UNC path, Transoft therefore strongly recommends opening a port, if you wish to open the printer directly. If the printer is not directly connected to the port, the port can be captured to the required printer. This must be done on the Windows 95/98 machine acting as the server prior to running U/BL.

Communications

COMMREAD on channel 16

'Console' input Channel 16 is not a serial line under Windows versions of U/BL. Therefore an implicit COMMREAD on channel 16 does not work.

COMMSET/COMMGET buffer size

The buffer size cannot be changed after the port is opened, and so COMMSET ignores the buffer size and COMMGET returns a value -1 for its size.

Flow control

Windows cannot support XON or XOFF separately, and does not support IXANY. If either IXON or IXOFF are set, XON/XOFF is supported in full. Also, it is not possible to read back the existing line settings using a COMMGET statement. For this reason, the Windows version of U/BL returns -1 for the MODEM; FLOW; VMIN and VTIM information on a COMMGET statement. Under SETPORT, mark and space parity types are not supported.

Supported baud rates

U/BL for Windows supports rates of up to 256000 baud, hardware dependant.

TCP/IP limitation under Windows 95

Under Windows 95, BYEing off does not always automatically close the TCP/IP connection, and so pressing space does not result in the connection being re-established. This is a confirmed bug in Windows 95 (KB article Q150523) which Microsoft are researching.

VMIN/VTIM support

The VMIN and VTIM line settings work differently from the UNIX version of U/BL. Under Windows the following settings must be used:

vmin=0, vtim=0 Return immediately from read.

vmin=0, vtim>0 Wait for up to a total time of vtim/10 seconds.

vmin>0, vtim=0 Wait until the read is satisfied.

vmin>0, vtim>0 Each character must come within vtim/10 of the last character.

These settings, once made, cannot be read back by U/BL. Any COMMGET returns values of -1 for both VMIN and VTIM (as well as the FLOW and MODEM characteristics). This is an operating system limitation.

Miscellaneous issues

$WPEDIT’s spell checker

Normally, under UNIX, $WPEDIT’s spell checker latches into the spelling checker provided as part of the operating system. Under U/BL for Windows this is not currently possible. We will investigate the feasibility of adding this functionality in a future release.

SYS(30)

SYS(30) sets bit 2^23 (8388608) for Windows NT or Windows 2000, or bit 2^24 (16777216 ) for Windows 95/98/Me.

System calls ($EXECUTE, STME 19, ^, !)

On Windows as with UNIX, system calls are executed on the server machine. The user must ensure that the only system calls made are console or MS-DOS programs such as DIR. Trying to call programs, which bring up a window may cause U/BL to hang. This is because any Windows applications started from U/BL are run on the server and so attempt to run on the desktop of the server machine. As this is a different machine from the client PC, the user neither sees nor is able to interact with the new process (as it is running on the server and knows nothing about the client PC). As U/BL is waiting on termination of the child process, it therefore appears to hang until the Windows program terminates. The problem is further compounded if the user is running with the setting UBLNTLOCKWORKTOP=L in their environment, as this ensures that the command started on the server is not visible.

U/BL NT debugging options

In case of unexpected behavior, the environment variable UBLNTLOG can be set to a filename where a log file of system services will be recorded. This can be set on a per-user basis with the U/BL Administrator. Note that UBLNTLOG will not work if set within a BBENV file; it must be set through the system control panel or the U/BL Administrator. If you want this setting to apply to all users the logging facility may be turned on via the U/BL Control Panel. Remember that the U/BL run-time has to be restarted before this change takes effect.

Similarly, the U/BL server process can be debugged by either setting the environment variable UBLNTMONLOG (to an appropriate filename) or specifying the log file via U/BL’s Control Panel.

Return from system calls ($EXECUTE, STME 19) under Windows 95/98/Me

Owing to the way in which COMMAND.COM operates under Windows 95/98/Me, the U/BL $EXECUTE and STME 19 statements are unable to return the exit status of the system command. A work-around for this operating system imposed limitation is to create a batch file similar to the following:

%1 %2 %3 %4

ECHO %ERRORLEVEL% > C:\TEMP\RESULT

Rather than directly issue the $EXECUTE or STME 19 statement, call a subroutine or shared procedure similar to the following:

@EXEC

REM ** New $EXECUTE routine for Windows 95/98

LET NEWCMD$="C:\MYCMD.BAT  ",CMD$

REM $EXECUTE NEWCMD$,EX

OPEN FILE[0,3],"C:\TEMP\RESULT"

READ FILE[0],EX$

LET EX=VAL(EX$,DUMMY)

CLOSE FILE[0]

RETURN


Terminal Definition File

The Terminal Definition File (TDF) is used by U/BL to determine the characteristics of the screen (vdu) and keyboard (kbd). This enables terminals with different screen and keyboard characteristics to be mapped as DG DXXX type terminals and use U/BL. A number of different TDF files are included with U/BL.

Screen Attributes Re-definition

U/BL understands certain keywords for each screen characteristic. Each keyword is followed by the value that the particular terminal screen expects. These attribute values can be determined by consulting the appropriate reference manual for the terminal. The keywords available are as follows with their meaning and expected values:

Keyword | Typical Value | Meaning/Valid Value
code | ascii | ascii or binary
ed | lb,5b,30,6d,lb,5b,31,6d,lb,5b,32,4a | erase display
cuu | lb,5b,41 | cursor up
cup_prefix | 1b,5b | cursor prefix
cup Jnfix | 3b | cursor infix
cup_suffix | 48 | cursor suffix
cud | lb,5b,42 | cursor down
cut | lb,5b,43 | cursor forward
cub | lb,5b,44 | cursor back
el | lb,5b,4b | erase line
st_us | lb,5b,34,6d | start under-score
end_us | lb,5b,30,6d,lb,5b,31,6d | end under-score
t_bl | lb,5b,35,6d | start blinking
end_bl | lb,5b,30,6d,lb,5b,31,6d | end blinking
rowoffset | 0 | row offset from 0
coloffset | 0 | column offset
rem |  | from 0
st_dim | lb,5b,30,6d | start dim
end_dim | lb,5b,30,6d,lb,5b,31,6d | end dim
st_rev | lb,5b,37,6d | start reverse
rem |  | video
end-rev | lb,5b,30,6d,lb,5b,31,6d | end reverse video
order rem | row,col | row,col or col.row
box | da,bf,d4,be,c4,cd,b3 | window boxing characters.
Order of window boxing characters: Topleft, Top right. Bottom left, Bottom right. Top line. Bottom line. Vertical.
vdu | 7b,82 | screen mapping characters
The vdu command causes the first character (7b) to be replaced by the second (82) on all output to the screen.
nrows=18 |  | hex for 24 rows
ncols=50 |  | hex for 80 cols
Defines the size of the screen and whether the terminal autowraps automatically.
autowrap=01 |  | 01 if terminal autowraps 00 default, if non-autowrap

Note: Only printable ASCII characters are allowed in the TDF. Do not use any control characters, such as TAB.

Screen Attributes

TDF Enhancements

The following TDF keywords enhance and improve the action of U/BL on non DG screens. These enhancements also enables proper line-drawing support on non DEC VT type terminals.

TDF Keyword | Function
init | Defines a sequence sent to the terminal when U/LB starts. Typical use is to select a line drawing character set.
term | A sequence issued when U/BL terminates to re-initialise the terminal to the state it was prior to executing U/BL. This is particularly useful when the vi editor is used after exiting U/BL.
gron & groff are automatically used by the @(-100,n), windowing and boxing
gron | A sequence to enter 'graphical' mode
groff | A sequence to exit 'graphical' mode
box | Extended from 7 to 16 entries.
compressed | A sequence to enter a 'compressed' mode (usually 132 cols by 24 rows)
normal | A sequence to enter 'normal' mode (usually 80 cols by 24 rows)
ncol | Extended to an optional 2nd value, which specifies the no. of columns in compressed mode.
nrow | As ncol but for rows
cur off | A sequence to turn the cursor off
cur on | A sequence to turn the cursor on
@(-nn) | Where 'nn' is any decimal value. It can be a user defined sequence or one of the 'standard' @ sequences, for example, @(-38) set dim on.
The following keywords support erasing from the cursor to end of screen and also the attribute settings support terminals where attribute setting is not additive but destructive replacement.
ereos | Erase to end of screen
at'n' | Attribute 'n', for example, atl through atl6

PRINT @(-..)

See Appendix G for the PRINT @(-...) sequences supported by the TDF.

Data General screens use ASCII characters in the range 1-127 and therefore any character that is outside this range will require mapping. This particularly applies to foreign character sets. For example the French 'e' with an accent, which is ascii 130 (hex 7b) would be held on file or in a program as (, which is ascii 123 (hex 82). Hence the entry above:

vdu     7b,82

In addition to the screen mapping, a similar mapping is required from keyboard to program. Further details on the syntax of this are given under Keyboard Re-assignment below, but to complete this example:

kbf_fr_e=82 : French e FROM keyboard

kbt_fr_e=7b : TO program as (

In this example under MS-DOS, it must be remembered to use the French keyboard driver KEYBFR.

NOTES on Screen Attributes Re-definition

  1. Under-score, blinking, dim and reverse video can be set instead to show differing colours on colour terminals, see COLOR.TDF.

  2. All values above are entered as hexadecimal values, except for:

Keyword | Valid Entries
code | ascii or binary
rowoffset | } decimal number
coloffset | } usually 0
order | row,col or col/row

  3. For VT100, 220, 320 terminals the correct box line characters are displayed automatically, so 'box' should NOT be included.

  4. In the TDF file comments start with a REM statement. Comments may also be appended to the end of a valid TDF description by the use of the colon ':'. A colon on its own in a line will cause a fatal error when involving U/BL.

  5. Although PC monitor screens have 25 lines, under Windows, U/BL uses the 25th line for Multi-Tasking messages, @(-42) /@(-43)- scroll/page mode - are now supported.

  6. The values above are examples of a Windows PC screen requirements.

Keyboard Re-assignment

The keyboard (kbd) entries allow the character codes generated by a particular key to be redefined into a different character sequence to be passed to the Business Basic program. The syntax requires a pair of entries as follows:

kbf_description=hex values | FROM - character code sequence generated by keyboard
kbt_description=hex values | TO - character code normally generated by a DG DXXX terminal keyboard and accepted by the program.

There is one special keyboard redefinition for the primary IKEY:

esc          hex value

For example:

esc 03

primary ikey = CTRL C

NOTES on Keyboard Re-assignment:

  1. The values are always in hexadecimal.

  2. The ' description' is not recognised by U/BL and is used for documentation purposes only. The description may be a maximum of 5 characters.

For example, to redefine Function Key 1 on a PC, under Windows, to generate the same byte pattern as a Data General Dasher DXXX's Function Key 1 use the following pair of entries:

kbf fl=00,3b : FROM - byte pattern generated by PC running Windows

kbt fl=le,71 : TO - byte pattern generated by DG Dxxx

While running U/BL, every time Function Key 1 is pressed on the PC terminal's keyboard, the byte sequence 'le,71' will be sent to the application program.

  3. Certain keyboard values when received by U/BL action HOT KEYS and the HELP KEY.

The 10 HOT KEYS are defined by the values decimal 201 to 210, that is, hex c9 to d2.

The HELP KEY is defined by the decimal value 200, that is, hex c8.

  4. Under Windows, the 9 multi-tasks can be obtained by ALT Fl to ALT F9 or the 'next- task by ALT F10.

  5. The sample TDF files supplied, with the UBB System Software, contain the following specific keyboard re-definitions:

  • Newline (primary unpend) is mapped to be the RETURN key and carriage Return (secondary unpend) to be CTRL J.

  • Primary IKEY is set to CTRL C (i.e. esc 03)

  • Delete Key reassigns backspace key to be delete key

kbf_del=08

kbt_del=7f

  • Function Key 11 is remapped to Shift Function Key 1.

  • The 10 HOT KEYS are defined by CTRL Fl to CTRL F10. Note not all terminals are capable of generating unique character sequences for Fl, SHFT Fl and CTRL Fl etc.

  • The HELP KEY is defined by SHIFT F10 or F15.

  • Support of CTRL H with STME 27.

The STME 27 editing function CTRL H, returning the cursor to the left end of the input, is supported, but the Terminal Definition Files map the -DEL key to also be a delete character, in addition to the other .DEL key. The -DEL key is normally Hex 08 (the same as CTRL H) and this is mapped to hex 7f, the DG delete character key.

Thus the options are:

* remove the -DEL mapping so that CTRL H works, or

* remap, say, the HOME key to output hex 08.

Keyboard Tester for Terminal Definition Files

It is often difficult to establish what characters a particular Terminal Definition File (TDF) is producing from the keyboard, particularly if a mistake has been made in the mapping of a specific character. This applies very often to function keys.

The utility 'TDFTEST written in Business Basic allows any TDF to be tested to show the main screen characteristics of 'clear screen', 'erase line', 'cursor movements', 'dim', "blinking', 'underscore' and 'reversevideo'.

In addition, any key may be entered and its decimal, hex and octal values displayed. Note that some keys produce two (or more) values when hit, for example, function keys.

To establish the actual values that a particular keyboard produces, use the TDF 'screen.tdf' as this has no keyboard re-definitions set. These hex values are then used as the 'FROM the keyboard' values in the TDF being developed.

Using a DG Dxxx Terminal under Unix/Xenix

If you use a DG Dxxx terminal, or a terminal running with binary (not ASCII) escape sequences, ensure you include:

stty-opost

in the '.profile' 'logon' file.

Example Terminal Definition File

See Appendix M for a sample TDF file.


TDF Keywords

Keyword

Possible Values

code

ascii / binary

The method of specifying the way in which the screen co-ordinates appear in cursor positioning sequences:

ascii => as ascii values, for example, 31,30 => 10

binary => as numeric data, for example, Oa => 10

init

Sequences of 2 digit hex numbers.

Defines a sequence sent to the terminal when U/BL starts. Typical use is to select a line drawing character set.

term

Sequences of 2 digit hex numbers.

A sequence issued when U/BL terminates to re-initialize the terminal to the state it was prior to executing U/BL. This is particularly useful when the 'vi' editor is used after exiting U/BL.

The gron and groff statements are automatically used by the @(-100,n) windowing and boxing functions. See Appendix G.

gron

Sequences of 2 digit hex numbers.

A sequence to enter 'graphical' mode.

groff

Sequences of 2 digit hex numbers.

A sequence to exit 'graphical' mode

compressed

Sequences of 2 digit hex numbers.

A sequence to enter a 'compressed' mode (usually 132 cols by 24 rows)

normal

Sequences of 2 digit hex numbers.

A sequence to enter 'normal' mode (usually 80 cols by 24 rows)

cur_off

Sequences of 2 digit hex numbers.

A sequence to turn the cursor off.

cur_on

Sequences of 2 digit hex numbers.

A sequence to turn the cursor on.

@(-nn)

Sequences of 2 digit hex numbers.

Where W is any decimal value. It can be a user defined sequence or one of the 'standard' @ sequences, for example, @(-38) set dim on.

ereos

Sequences of 2 digit hex numbers.

Erase to end of screen.

at'n'

Sequences of 2 digit hex numbers.

Attribute 'n', for example, atl through atl6. These keywords provide support for terminals where an attribute setting is not additive but destructive replacement.

cup_prefix

cup_infix

cup_suffix

Sequences of 2 digit hex numbers.

Escape sequences that together with the row and column data specify cursor positioning. The general format is:

prefix,<A>,infix,<B>,suffix
[<A> & <B> specify the position]

order

row,col / col,row

Specifies which argument to the cursor positioning sequence is first.

rowoffset

coloffset

Decimal number.

Used where 'mode' is 'binary'; indicates the offset added to the row/col values to generate the cursor positioning sequence, for example, If row 1 is represented by 32, that is, 1 + 31, in the cursor sequence, then rowoffset is 31.

Cuu

Sequences of 2 digit hex numbers

Escape sequence to move cursor up 1 line (perform an '@(-24)').

cud

Sequences of 2 digit hex numbers

Escape sequence to move cursor down 1 line (perform an '@(-22)').

cuf

Sequences of 2 digit hex numbers

Escape sequence to move cursor forward (perform an '@(-21)').

cub

Sequences of 2 digit hex numbers

Escape sequence to move cursor backwards (perform an'@(-23)').

autowrap

00 / 01

Specifies if hardware wrapping is not supported (00) or where is is

roll.on

Sequences of 2 digit hex numbers

Escape sequence to allow scroll. (Used when PRINTing ascii <18>.)

roll.off

Sequences of 2 digit hex numbers

Escape sequence to set page mode. (Used when PRINTing ascii <19>.)

ed

Sequences of 2 digit hex numbers

Escape sequence to clear display, (perform an '@(-30)')

el

Sequences of 2 digit hex numbers

Escape sequence to clear to the end of the current line, (perform an '©(-32)')

st.us

st.bl

st.dim

stjrev

Sequences of 2 digit hex numbers

Escape sequence to switch on the specified screen attribute us=underline, bl=blinking, dim=low intensity, rev=revers.video.

end.us

endbl

end.dim

endjrev

Sequences of 2 digit hex numbers

Escape sequence to turn off the specified screen attribute us=underline, bl=blinking, dim=low intensity, rev=reverse video.

Alternatively, these screen attributes (specified in the two rows above) may be expressed as:

@(-38) Low intensity on

@(-39) Low intensity off

@(-40) Blinking on

@(-41) Blinking off

@(-52) Underline on

@(-53) Underline off

@(-57) Reverse Video on

@(-58) Reverse Video off

Note: The above are sequences of 2 digit hex numbers.

box

Sequences of 2 digit hex numbers

Defines the characters used for the outlining of windows. They appear in the following order:

Box Position | Graphic
1 | Top left hand
2 | Top right hand
3 | Bottom left hand
4 | Bottom right hand
5 | Top horizontal
6 | Bottom horizontal
7 | Vertical
8 | Left intersection
9 | Right intersection
10 | Top intersection
11 | Bottom intersection
12 | Cross

kbf

kbt.

Sequences of 2 digit hex numbers

These two entries allow for the mapping of keyboard returns FROM the sequence generated by the keyboard, 'kbf_...' TO the specified 'kbt_...' sequence.

nrow

2 digit hex number, {2 digit hex number}

This entry specifies the number of rows on the screen.

It is a hexidecimal number, with an optional second hexadecimal number specifying the numbers of rows in compressed mode.

ncol

2 digit hex number, {2 digit hex number}

This entry specifies the number of columns per screen line.

Like nrows it is a hexidecimal number, with an optional second hexadecimal number specifying the numbers of columns in compressed mode.


U/BL Windows, Menus and Help

U/BL provides the following features:

* Windows

U/BL allows windows to be created in, for example, a driver program and then be actioned throughout the application. All activity within a window takes place relative to its top left hand corner, the HOME position.

* Menus

U/BL provides Lotus type (circular menus) and narrow and wide Pull Down menus within windows.

* Debug Window

A Debug Window is provided to preserve the 'current' screen display when using the Debug facilities. The Debug Window displays any break points, watched variables and so on.

LISTing and other debugging may take place within the window. When the program is CONed the Debug Window disappears and the original screen is redisplayed.

* Help

A menu of help items and corresponding text is displayable within a Help Menu and Window at the press of a Hot Key.

Note: No reprogramming of the existing application is required.

These features are available on all versions of U/BL.

Support of 132 Character Windows and Menus

Windows and Menus can be defined and used in a 132 column mode (or other widths if the terminal supports it). In general moving from 80 to 132 or back again erases the screen so all windows should be hidden.

The following TDF Terminal Definition File keywords support this functionality.

compressed | A sequence to enter a 'compressed' mode (usually 132 cols by 24 rows)
normal | A sequence to enter 'normal' mode (usually 80 cols by 24 rows)
ncol | Extended to an optional second value which specifies the number of columns in compressed mode.
nrow | As ncol but for rows.

U/BL also supports the following PRINT @(-..) sequences defined by TDF enhancements, for the compressed and normal screen modes and others:

@(-132) | Enters 'compressed' screen mode
@(-80) | Enters 'normal' screen mode
@(-nn) | If 'nn' has been defined as a user sequence in the TDF this is sent to the terminal
@(-100, n) | Prints graphical character 'n' as defined in the 'box' sequence.
@(-101) | Cursor on
@(-102) | Cursor off (hide cursor)
@(-33) | Erase to end of screen.

PRINT@(-60), @(-61) or @(-62) functions:

PRINT @(-60) - Toggles the windows state between on and off

PRINT @(-61) - Turns windows off

PRINT @(-62) - Turns windows on

Although U/BL allows you to define your own print table, PRINT @(-61) and @(-62) will affect the U/BL window facility, as well as sending the sequence of characters defined by these @ codes in your TDF Terminal Definition File to the screen.

PRINT @(-61) will automatically turn windows off (if set), turn raw input on, and send the sequence identified by @(-61) in your TDF file to the screen. PRINT @(-62) will send the sequence identified by @(-62) in your TDF file to the screen, before switching the window facility back on.

For example, the following TDF file entries to control Print Passthrough will also switch the window facility off and on:

@(-61)=lb,5b,03 : Windows OFF, print-pass-through ON

@(-62)=lb,5b,04 : Print-pass-through OFF, windows ON.

You can, of course, use @(-61) and @(-62) to define any sequence, which needs to switch off the window facility temporarily.

Transparent PRINTing for Print Passthrough (All platforms)

U/BL supports a transparent PRINT mode. To use the, issue the STMA 6,102 statement followed by the Print Passthrough-on escape sequence to enable, and the Print Passthrough-off escape sequence followed by the STMA 7,102 statement to disable.

Once enabled, all output to the screen is "raw", apart from New-line (NL) and Carriage Return (CR). This mode has the same effect as running with the BBRAWOUT environment variable set, and also acts as if the BBWINDOWS environment variable. For true raw mode, including NL and CR, use the STMA 6,103 statement.

Example (substitute the appropriate Print Passthrough (ppt) sequences):

100 LET PPTON$="<ppt-on>" \ PPTOFF$="<ppt-off>"

200 STMA 6,102

210 PRINT USING "",PPTON$

: output to be passed through to the local printer

300 PRINT USING "",PPTOPF$

310 STMA 7,102


U/BL Windows

If windows are required then the BBWINDOWS environment variable must be set to Y, for the default window buffer size or set to the size of the buffer you require.

Up to 120 windows may be initialized, subject to memory, and created for subsequent use by any other programs.

This initialization and creation may take place in a driver program or the initial menu. Others can be created later as and when they become necessary. Once created any window can be 'actioned' anywhere within a system provided the program that actions the window has been SWAPped or CHAINed to by programs that follow the window creation program.

Having initialized and created the windows, you may:

  • SHOW a window

  • MOVE a window

  • HIDE a window

  • Pull a window to the TOP

  • Push a window to the BOTTOM

  • DELETE a single window

  • ERASE all windows

  • MINIMISE a window

  • RESIZE a window

  • TITLE a window

  • SCROLL up or down a region of a window

  • PRINT to hidden windows

Many windows may be present on the screen at any time, but only one is currently active which is on 'top' of all the others.

Any U/BL program screen activity being processed within a window will be relative to its top left hand corner, for example, @(1,25) in a window with top left coordinates of (10,10) will be equivalent to @(11,35).

Note: When windows are created they are relative to position (0,0).

Window Statements

The generalised syntax of a Windows statement is:

[REM] W<keyword> ({parameters)[,stat])

where:

the REM is optional and stat returns:

-1 | No windows
0 | For no error
1 | Not found
2 | Duplicate
3 | Not visible
4 | Already visible
5 | Invalid name
6 | No memory
7 | Illegal command
8 | Incorrect buffer length
9 | Exceeding max number of windows.

In most cases the stat variable is optional.

Note: In U/BL to optimize performance, it is recommended that menu objects, for example, WCREATE, WMAKE, MCREATE are created in, for example, an initialization program at start up. This will increase the performance of the MACTION or WSHOW statements.

U/BL supports the following windows statements:

BOX(ru,cu,rl,cl) - Creates a box of the size specified

WATSAY(wnam$,row,col,str$,attr[,stat]) - Displays a string of text in a window

WBOTTOM(wnam$[,stat]) - Puts a window to the bottom of the stack

WCLEAR(wnam$[,stat]) - Clears a windows

WCREATE(wnam$,wd$[,stat]) - Creates a window.

WDELETE(wnam$[,stat]) - Physically deletes a window

WERASE([stat]) - Erases all windows

WHIDE(wnam$[,stat]) - Hides a currently displayed window

WINFO(wnam$,x$[,stat]) - Obtains information on a window

WINIT(stat) - Initializes a window

WMAKE(wnam$,row,col,nrow,ncol,flags[,stat]) - Makes a window within a program

WMOVE(wnam$,row,col[,stat]) - Moves a window on the screen

WOFF - Turns a window off from within a program.

WON - Turns a window on from within a program.

WRESIZE(wnam$[,row,col,nrow,ncol,stat]) - Changes a window’s size and position

WRESIZE(wname$) - Restores a window to original position and size.

WSCROLLDOWN(n[,stat]) - Scrolls a window region down

WSCROLLUP(n[,stat]) - Scrolls a window region up.

WSHOW(wnam$[,stat]) - Displays a window on the screen

WSREGION(top,bottom[,stat]) - Defines the scrolling region of a window

WTITLE(wnam$,t$,attr[,stat]) - Puts a title on to a window

WTOP(wnam$[,stat]) - Brings a window to the top of the stack on screen.


U/BL Menus

There are three different types of menus available:

  • Lotus 123 Type Circular Menu

  • Wide Pull Down Menu

  • Narrow Pull Down Menu

Menus use windows, so you have to create a window first before you can create a menu. The size of the window will depend on the menu type and the number of items to be displayed. Care must be taken when defining the window because consideration must be made of boxing, shadowing and item descriptions.

Both the Circular and Wide Pull Down menus have descriptions for each menu choice. The difference between the Pull Down Menus is that the Wide version can have a description against each menu keyword.

All these menu types must exist within windows. Like all other windows, menus and their windows are initialized and created once, in, say, a driver program, and then actioned whenever required.

Menus can be:

  • Created

  • Actioned

  • Deleted

To create menus, create the necessary windows in the driver program along with all the other windows (see the WCREATE and WMAKE statement sections).

The size of these windows depends on the type of menu; the Lotus type being wide across the screen and narrow in depth; the narrow Pull Down is narrow across the top and long in depth and the wide Pull Down is wider across the top.

`

The Lotus type menu has three lines to be printed. If the window is to be boxed then it must be 5 rows deep and if boxed and shadowed then it must be 6 rows deep. The width of the window can be any size because if there are more menu items than can be displayed in the window then use of the arrow keys will scroll the menu items through the window.

The Narrow Pull Down window width will be determined by the longest keyword in the menu plus 2 additional columns for boxing and a further column for shadowing, if these facilities are included.

The Wide Pull Down window width is that calculated for a Narrow Pull Down plus the width of the maximum description plus one further column.

The depth of a Pull Down menu window is independent of the number of menu items as, again, these can be scrolled through the window by using the arrow keys.

Headings and other layout information, including 'blank lines', can be included in Pull Down menus.

Cut and Paste

If an additional string variable is specified in the MACTION statement then the text of the menu item selected is returned in this string.

This may then be placed in the user's input buffer via the STME 27 statement.

This is typically used when you Hot Key from, say, a maintenance program to a program showing a code look up in the form of a Pull Down menu. You can then select the code you require and 'cut' it from the window and 'paste' it back in the field you left in the maintenance program.

Menu Selection Logic

To make a selection from a menu, you can use the cursor keys or enter one or more characters that make up a unique leading part of the selection. As each character is entered the cursor jumps to the 'first' item with that combination of leading characters. When a menu has to scroll up or down by cursor movement the resultant window centres on the current item.

After selecting an item, the item number is returned to the program and the window with the menu disappears, unless 'permanance' has been attributed to the menu window. The item number can then be acted upon.

To clear a menu window with the 'permanance' attribute set, use the WHIDE statement.

Keyboard Support

Four functions are available in Help and Menu processing. These functions, and the keys that access them, are:

HOME actioned by <SHIFT-F1> (maps to le,61) or <C1> (maps to le,5c).

PAGEUP actioned by <F1> (maps to le,71) or <C2> (maps to le,5d).

END actioned by <SHIFT-F1> (maps to le,62) or <C3> (maps to le,5e).

PAGEDOWN actioned by <F2> (maps to le,72) or <C4> (maps to le,5f).

These can be mapped in your TDF Terminal Definition File. For example, the entries could be as follows:

kbfhome=<sequence returned by your keyboard's HOME key>

kbt_home=le,5c

These keys have the appropriate effect during Help and Menu actions.

Menu Statements

The Windows package generalised syntax is:

[REM] M<keyword> ({parameters)[,stat])

where:

the REM is optional and stat returns:

-1 | No windows
0 | For no error
1 | Not found
2 | Duplicate
3 | Not visible
4 | Already visible
5 | Invalid name
6 | No memory
7 | Illegal command
8 | Incorrect buffer length
9 | Exceeding max number of windows.

In most cases the stat variable is optional.

Note: In U/BL to optimize performance, it is recommended that menu objects, for example, WCREATE, WMAKE, MCREATE are created in, say, an initialization program at start up. This will increase the performance of the MACTION or WSHOW statements.

U/BL supports the following Menus statements:

MACTION(mnam$,act[,stat[,code$][,item]]) - Use to action a menu

MCREATE(mnam$,wnam$,h$,i$,d$,type[,stat]) - Used to create a menu

where type can have the following values:

0 | ALL Pull Down Menus
1 | Lotus type menu

MDELETE(mnam$,STAT) - Used to delete a menu (but not the window it is in)

MFKEY(mnam$,fkey,rval[,stat]) - Used to define menu function keys

where fkey can have the following function key values 1-21:

1-15 | Function keys 1 through 15
16 | HOME
17 | END key
18 | PAGE UP or Up arrow of top of menu
19 | PAGE DOWN or Down arrow of bottom of menu
20 | HELP key
21 | Invalid accelerator key used (i.e. an invalid first character of a menu item is used)

The rval parameter returns the value when the function key is pressed.


U/BL Help

General Help

Any program may have a Help menu and text associated with it, without any additional code being added to the program itself.

There are two windows, which are provided as defaults within U/BL, in which the help details are displayed. Firstly, there is a Pull-Down menu, which is called HELP_INDEX, and secondly, there is a window for the text itself, called HELP. If you prefer to have help index menu and text windows of different sizes then they may be created as for any other windows but with the specific names of HELP_INDEX and HELP.

The standard sizes of the two windows are:

 | Start |  | Total
 | Row | Col | Rows | Cols
HELP_INDEX | 5 | 63 | 18 | 15
HELP | 10 | 4 | 13 | 55

The help text file is defined in U/BL by using the BBHELP environment variable.

For example:

BBHELP=C:\UBL\HELP\HELP.TXT - Under Windows

BBHELP=/user/data/helpfile - Under UNIX

It is possible to have a number of different help text files associated with an application, with the content of BBHELP being changed by the $PUTENV statement at appropriate points within the menu program.

However, it will be easier to have the help text for any number of programs in one text file. The text for any program starts with:

.program.name {program_namel program_name2}

and continues until the next '.program.name' is reached or End Of File,

Note: Multiple programs may have the same help text and the line must start with a '.' full stop.

The text for any particular program may be sub-divided into sections detailing particular items. These items are denoted in the text as:

!item.name

It is these items that will appear in the HELPJNDEX window. As with any entry in a Pull-Down menu the items may be selected via use of the up and down arrow keys, the space bar or entry of one or more characters that make up a unique leading part of the selection.. When an entry is selected by pressing the ENTER key, the main HELP window appears with the start of the text for that section displayed.

The text may be paged up and down using the Fl and F2 function keys or using the up and down arrow keys.

The DEL or ESC key are used to exit from the HELP text window and cause it to disappear and return to the HELPJNDEX window.

Further items may then be selected or processing returned to the program by pressing the DEL or ESC keys again.

An example of a help text file may look as follows:

.DEMWIN

!Multi-tasks

Under Windows up to 9 U/BL tasks are available at the press of Hot Keys.

!Windows

An improved window facility allows any number of windows to be initialised in, say, a driver program and then be actioned throughout the application. All activity within a window takes place relative to its top left hand corner.

!Menus

UBB supports Lotus type (bar menus) and narrow and wide pull-down menus within windows.

.NEXTPROGRAM

etc.

Then, in this case, the HELPJNDEX entries will be:

with the associated text on selection of each of these items, as shown.

Notes:

  1. The text may be created with any suitable word processor but the final output must contain only ASCII characters.

  2. There is no need to format the text to be the width of the HELP window as U/BL automatically performs word wrap, except on lines beginning with spaces or tabs, in which case they are shown as stored in the text file.

Help Enhancements

The following keywords can be added to help text files:

:INCLUDE

Include text from another file. For example:

:INCLUDE xyzhelp.123

will include the contents of the file xyzhelp.123 in the current help text. The file is expected to be in the directory component of the BBHELP environment variable.

Note: The file to be :INCLUDEd must only be text, and it cannot be another Help file, that is, it cannot contain any "." lines.

:INDENT

This keyword will indent subsequent text by the specified number of characters from the left margin. It can be abbreviated to IND. For example:

:INDENT 5,

is equivalent to:

:IND 5

:INDENT 0 will switch indentation off.

:WINDOW row col nrpw ncpl flag
:MENU row col nrow Hcol Hag

These keywords can change the size of the Help main window and the associated Menu window at any number of points within the help text file. The arguments have the same meanings as those used in the WCREATE and WMAKE commands.

Example of Help file:

.prog1

:WINDOW 5 5 10 50 7

:MENU 5 20 10 18 7

!Item 1

Text for Item 1

!Item 2

Text for Item 2

:WRAP

This keyword turns word wrap on, which is the default on start up. Tabs are compressed to a single space.

:NOWRAP

This keyword turns off word wrap and tabs are expanded using the current tab setting. The default tab setting is 8 characters. Word wrap can also be controlled by the BBNOWRAP environment variable. If BBNOWRAP=Y, then 'no word wrap' is set.

:REM

Any lines starting with this keyword are ignored, so statements or even control codes for other software can be inserted, for example, Word Processing or Desktop Publishing.

:TAB n

This keyword sets the tab size to 'n' spaces, for example, :TAB=10. The default tab setting is normally every eight characters. The default can, however, be controlled by the BBTAB environment variable, for example, BBTAB=5.

Context Sensitive Help

Additional information can be added to Help Menu item definition lines ("!" lines), to define the screen area associated with the subsequent Help text. The format of this definition is:

@(row,col,len)

where:

row | The screen row on which the item appears.
col | The screen column at which the item appears.
len | The length of the item.

Example

!Address @(10,15,30)

When the HELP key is pressed, and the cursor is in the area of the screen defined by row, col and len, the relevant text will be displayed without the Help Menu being shown first. If the HELP key is pressed again while the text is still on the screen, then the Help Menu will be displayed.

If the BBHBUILD environment variable is set, then each time the HELP key is used, the user is asked to provide a field length and menu item name. This information, together with the current screen coordinates, is appended to the end of the file identified by the BBHELP environment variable.

In this way, context sensitive help messages can be created easily. Once all of the context sensitive help details have been entered, BBHBUILD should be switched off.

Help Indexing and Help File Redirection

It is possible to 'index' a help text file to improve look up performance. A program, HINDEX.BB, is provided to convert a non-indexed help file into an indexed help file. U/BL can detect if an help file is indexed and uses the index accordingly.

Also the help file can refer to separate file(s) which contain the actual help text. If a '.' line defining program names is ended with a redirection specification, that is:

< filename

then the help text for the program(s) on this '.' line is taken from the named file.

Example

. proga progc proge < /usr/help/ledger.hip

U/BL will look for the help re-direction text file firstly as an absolute pathname and if not found then relative to the directory portion of BBHELP.

Alternate Help text selection

When the Help Hot Key is hit in any program the Help facility searches the Help text file, defined by BBHELP, for the entry:

. progname

When found the text following is selected.

If the BBHITEM environment variable is set to any name, for example, BBHITEM=genledger, then the Help facility searches the Help text file for both the program name and the BBHITEM name. Whichever is found first will denote the text displayed as the help.

This is useful for providing 'global' help across a number of programs.

The BBHITEM environment variable can be modified dynamically by the $PUTENV statement.

Global Help

If you wish to provide standard help text for any program that does not have specific help, then include at the end of the Help file the 'program' entry:

. *

Follow this entry by the Help !items and text in the normal way.

Change the Help-Index Menu Size

By default a maximum of 500 characters for DOS and 1000 characters for UNIX may appear in the Help-Index Menu (this is the total '!items' lines for the particular program). To increase this value set the BBHMEM environment variable to the number of characters you require.

The maximum number of item lines on a Help-Index Menu is 50.

Keyboard Support

Four functions are available in Help and Menu processing. These functions, and the keys that access them, are:

HOME actioned by <SHIFT-F1> (maps to le,61) or <C1> (maps to le,5c).

PAGEUP actioned by <F1> (maps to le,71) or <C2> (maps to le,5d).

END actioned by <SHIFT-F2> (maps to le,62) or <C3> (maps to le,5e).

PAGEDOWN actioned by <F2> (maps to le/72) or <C4> (maps to le,5f).

These can be mapped in your TDF file. For example, the entries could be as follows:

kbfhome=<sequence returned by your keyboard's HOME key>
kbtjiome=le,5c

These keys have the appropriate effect during Help and Menu actions.

Help Statements

HELP[(major$,minor$)] - Invoke Help within a program


Extended File System (EFS)

The Extended File System (EFS) allows files to be automatically extended, when their current limits are reached. The manual extending of files can constitute a major support burden. The EFS alleviates this burden without the need to reformat existing files.

Extended Indexes

Extended Indexes start off as conventional ISAM indexes, which are converted into an extendible index by using the INDEXEXTEND statement. An extendible index is one which can grow beyond its original disk allocation. If a logical index file exists in a physical file, it is possible that the index is followed by an area of disk allocated to another logical file. For example:

Normally, to allow the index file to extend past its original size, the whole data file would have to moved along in the physical file before re-sizing the index:

This is a very involved set of actions as any references to the start of the data need to be updated to reflect where the data file has been moved to. This process is further complicated if more than one file follows the index in the physical file. Extended files combat this by allowing the index to grow into space at the end of the physical file, rather than requiring the disk space to be contiguous as in "normal" ISAM indexes. These index extensions, or extents, are automatically created by the KADD statement once the initial disk space allocated by the index has been exhausted. The extent is always created at the end of the physical file which contains the index:

Technicalities

An Extended Index is created by running the INDEXEXTEND command against an existing ISAM or ISAM+ index. This process flags the index as being able to extend past the initial disk allocation. Extending the index is achieved by the KADD statement automatically adding a new extent to the end of the physical file whenever the disk space allocated to the index becomes exhausted.

The size of the extent, measured in index blocks is set by one of the parameters to the INDEXEXTEND statement. Once created, an Extended Index can grow a maximum of 64 times (that is, up to 64 extents can be created, this equates to extent_size * 64 extra index blocks). However, regardless of the number of extents in use, the size of the index cannot be greater than 65534 (standard ISAM) or 16777215 (ISAM+) index blocks. In addition the operating system limits on maximum file size apply, so the size of the physical file will be unable to exceed these.

Since extents are always created at the end of the physical file, the end of the physical file must be past the end of the last logical file contained in the file otherwise when the last logical file extends, it will overwrite any index extents that have been created. For example, consider the file:

If an index extent is created at the end of the file, we will have:

where the index extent has been created within the logical data file's disk space. This obviously gives us two files sharing the same disk space which will result in data corruption:

To combat this the INDEXEXTEND statement requires an extend_form parameter that confirms from what point it is safe to create index extents. When the index is flagged as extendible, the INDEXEXTEND statement will automatically enlarge the physical file should it be shorter than that required by the extend_form parameter (since any extent is added to the end of the physical file, this must be past the extend_form location hence the need to extend the physical file).

For example, considering the above file, we can calculate the extend_form value that is required:

Running an INDEXEXTEND statement against the index file, with the calculated extend_from will pad out the physical file as follows:

This functionality is only required if the last logical file in the physical file has not had all of its logical disk space allocated. If the last logical file has been physically created to its maximum size, the end of the physical file will obviously be at the end of the last logical file, thus negating the need to extend the file. Under such circumstances, specifying a value of -1 to the extend_from parameter will cause the INDEXEXTEND statement not to pad out the file.

Additionally, since this functionality effectively null fills the last logical file, it need only be used once per physical file. This is because the end of the physical file will be made to reflect the end of the last logical file on the first INDEXEXTEND, rendering any extension on subsequent INDEXEXTENDs redundant. For example, given the original physical file:

If one of the indexes is extended, the physical file will become:

And with the data file padded out to its logical length, any subsequent INDEXEXTEND need not pad the file (unless a new, un-filled logical file is created at the end of the physical file).

When a normal ISAM or ISAM+ index is extended, the structure of the index control block (block zero) is modified. The normal control information (held in bytes 1-14, and, if BBREUSE=Y, bytes 132-135) remains unchanged, but bytes 129-132 and 137-408 are initialised to hold the control information associated with an extended index. This control information can be summarised by the following table:

Offset | Length | Description
128 | 4 | Signature - the BBASIC string "<147>$<192><185>" for an extended index
136 | 4 | Number of blocks per extent
140 | 4 | Number of blocks used in the current extent (initially 0)
144 | 4 | Number of extents in use (initially 0, with a possible maximum of 64)
148 | 64*4 | Location (byte offset within physical file) of each of the 64 possible extents.
404 | 108 | Reserved

Programming Considerations

While the use of Extended Indexes is transparent as far as the K-operations are concerned, there are certain considerations that have to be made for file manipulation routines and utilities. All of these stem from the need to prevent extents from using the same areas of disk space as data files.

The first programming consideration is the problem of making sure an extent is never created at a point allocated to a logical file.

As discussed above, the method of ensuring this is via the extend_from parameter of the INDEXEXTEND statement when creating an Extended Index. However, this requires an explicit calculation of the last allocated byte in the file.

This calculation will involve reading all the layout information associated with the particular physical file (in the '.VL', PARAM or other control file) to find the starting point; length and thus end-of the last logical file in that physical file. For example,

A more automatic method would be to force the allocation of all a logical file's disk space when that file is defined. This would ensure that the end of the physical file represents the end of the logically allocated disk space.

As the most straight-forward method of disk allocation for extended files is to pad out logical files to their defined length, the Business BASIC utilities INITFILE, LFU, NWLFU and PARAMCON have been modified to extend all logical files to their defined length.

The second consideration is to prevent the creation of a logical file over the disk space allocated to an index extent.

Since the location of the index extents is not recorded, the normal operation of using the physical file's '.VL', PARAM or other control file to determine where to create the new logical file is unavailable. For example:

Assuming the convention of always padding out a logical file to its theoretical length has been adopted, the new logical file can be created at the end of the physical file. This is because in both possible cases, the end of the physical file is past either an extent or the end of the last logical file:

Case 1: A logical file is the last item in the physical file.

Case 2: An index extent is the last item in the physical file.

If, on the other hand, the end of the physical file does not reflect the end of the last logical file this approach cannot be taken. Under these circumstances the allocated disk space needs to be calculated so the free space can be determined. The calculation of the disk space allocated to the logical files defined in the physical file, is relatively straight forward. Using the starting location and length of each logical file from the control file determines the disk space allocated:

To find the regions of the file allocated to the index extents is also straightforward, if a little more involved.

For each logical index in the physical file, the index control block will have to be examined. Checking bytes 128-131 of the control block will determine if the index is extendible (the value of these bytes will be the BBASIC string "<147>$<192><185>" for an extended index).

Should the index be extendible, the location of any extents will be listed in the table held in bytes 148-403. This table holds the byte offset (from the start of the physical file) of each of the possible 64 extents.

The offset is held as a four-byte unsigned integer (PACK format “E”). Each extent, starts at the specified location and lasts for extent_size * block_size bytes, where extent_size is the size of each extent (bytes 136-139 of the index control block) and block_size is the block size of the index (odd value for byte 14 of the control block implies 2 048 otherwise 512).

As extending logical files to their logical file length and creating new files at the end of the physical file is the most convenient method of disk allocation when using Extended Indexes, the Business BASIC utilities LFU, NWLFU and PARAMCON have been modified to take this approach when creating logical files. Additionally, all of the other index manipulation programs (BUILDINDEX, IBLD, INDEXBLD, INDEXPRT, INDEXVRFY, IREBLD LINDEXBLD and LXFER) have been modified to support Extended Indexes.

The final aspect of Extended Indexes that needs to be considered while programming is the method of re-initialising an index that is employing extents. Normally, re-initialising an index involves the re-creation of Block 0 (the index control block). If this approach is used for an index that has one or more extent in use, the disk space allocated to those extents will be “lost”. This is because the only place that the location of these regions is recorded is the Block 0.

The recommended approach to re-initialising an Extended Index (in-order to allow re-use of the index extents) is as follows:

  • Gain exclusive control of the index in the usual manner

  • Reset the root-block to point to block 1

  • Reset the next available block to point to block 2

  • Write the usual "end of index block" as block 1

  • Reset the number of extents field to 0

  • Reset the “number of blocks used in the current extent” field to 0

  • If BBREUSE=Y, nullify the deleted record chain

Following this procedure will result in the preservation of the extent pointers held in the index control block. Preserving the extent pointers and re-setting the extents_used field allows the originally allocated extents to be re-used whenever a new extent is used. When a new extent is to be allocated, the KADD statement will check to see if the next extent_location pointer is set. If it is, the KADD will assume this is a previously assigned area of disk space and utilize that region, rather than create a new extent at the end of the physical file. This functionality prevents the existing disk space allocated to extents being “lost” when an Extended Index is re-initialised. The Business BASIC utilities INITFILE, LFU and NWLFU have been modified to perform this functionality.


ISAM+

ISAM+ indexes are based on standard, 2 048 byte Data General ISAM indexes. However, whereas normal ISAM indexes only allow for a maximum of 65534 index blocks, ISAM+ extends this limit to 1048575 index blocks (2 Gb of index). This is achieved by employing three, rather than two byte index block pointers.

Technicalities

In a standard ISAM index, three index block pointers are maintained in the index control block (the "Block 0") and two pointers in each index "leaf" block (an index block containing the actual keys).

All of these pointers contain the number (in the index) of the index block that they refer to and are made up of two bytes. The pointers held in the control block of the index reference the last usable block in the index (effectively the maximum number of index blocks); the "root" block (the index block at level 0, from which all other blocks emanate) and the next free block (the next block to be allocated). A leaf block contains pointers to the next and to the previous leaf block based upon the key sequence (the block before contains the key that precedes the first key in the current leaf block, the next block contains the key following the last key in the current leaf block).

With an ISAM+ index, all of the usual pointers are supported but instead of being two byte entities, they have been extended to employ three bytes. This increases their addressability from 0-65534 index blocks to 0-16777215. However, due to operating system limitations on the maximum size of a file, the actual addressability is restricted to a maximum of 1048575 index blocks.

As the pointers in a conventional ISAM index are consecutive, their length could not just be increased without moving their location. For this reason, the high byte of each pointer is held separately from the low word which remains in the original location. In order to identify an ISAM+ index, a signature has been added to bytes 15-16 of the control block. If these bytes contain the relevant signature (CHR$(12345,2)) the index is recognised as being an ISAM+ index with the following structure:

Format of the Block 0 (the index control block):

Bytes | Purpose
1-2 | Number of bytes per entry (length of key + 4 or length of key + 6 for indexes allowing duplicate keys, either way, must be an even length).
3-4 | Number of keys per block
5-6 | Pointer to last usable index block (maximum number of index blocks)
7-8 | Pointer to the next available index block (first free block)
9-10 | Pointer to the root block (the "level 0" index block)
11-12 | Blocking factor (holds number of keys per block at the specified blocking factor)
13 | Locking flag (set to one to force data file locking)
14 | A value of '3' implies duplicate keys are allowed, '2' forces unique keys.
15-16 | Signature for ISAM+, CHR$(12345,2) or the string "09"
17 | High byte of 'last usable index block pointer'
18 | High byte of 'next available index block pointer'
19 | High byte of ' root block pointer'

In addition, the following fields may optionally also be located in the index control block:

Bytes | Purpose
129-132 | Signature for an Extended Index
132-136 | Deleted index block chain (only if BBREUSE=Y)
137-408 | Extended Index information

Format of a block containing keys (a leaf block):

Bytes | Purpose
1-2 | Number of keys in the block
3-4 | Pointer to the next block in sequence
5-6 | Pointer to the previous block in sequence
7 | High byte of 'next block pointer'
8 | High byte of 'previous block pointer'
9+ | Key entries

Programming Considerations

The use of ISAM+ indexes is wholly transparent as far as the K-operations are concerned. The only programming implications come with utilities that manipulate the individual index blocks. All of the relevant Business BASIC utilities (BUILDINDEX, IBLD, INDEXBLD, INDEXPRT, INDEXVRFY, INITFILE, IREBLD, LFU, LINDEXBLD, LXFER, NWLFU and PARAMCON) have been extended to cope with ISAM+ indexes so that should a user create a 2 048 byte index and request to use more than 65534 index blocks, then the index will be created as an ISAM+ index rather than in the conventional ISAM format. Indexes that have already been created in the ISAM+ form are also automatically processed.

The only programming changes that will be necessary to support ISAM+ indexes will involve modifying existing index manipulation routines that reference any of the block pointers. This includes index initialization routines which must reset the high byte of all of the three block pointers in the control block. Since the pointers only employ the third, high byte in ISAM+ indexes this need only be done if the signature bytes are set to CHR$(12345,2). Any programs that read through the index blocks individually, using the block pointers will have to be modified to read in the extra byte when they reference the pointer. Once again, this functionality will be dependent on the ISAM+ signature being set.

One aspect of index processing that has not changed is that the end of the index is always identified by the block number of 65535. This is still the case for ISAM+ indexes and is achieved by this block being skipped as index blocks are created. Once block number 65534 has been allocated, the next block will be number 65537. Any BBASIC code that checks for the end of index therefore only needs to be modified to read in the extra pointer byte, rather than having to test against a different maximum value.


Shared Memory Procedures

Shared Memory Procedures are a 'shareable' body of U/BL code that multiple U/BL users can access. Typical uses of this facility would cover common routines for file I/O, database access and so on, that are normally included in each separate program.

The common routines reside in a shared memory segment and are loaded once at the start of the day. The shared memory segment is created by the U/BL Monitor Utility, UBLMON, and it's size is determined by the BBSHLIB environment variable. For example:

BBSHLIB=20000

Each loadable module is a U/BL program with one or more named ENTRY points. Associated with each ENTRY point is a list of arguments (formal parameters), which form the link to the calling program.

A U/BL program can call, using the PROCEDURE_NAME, the shared library entry points passing an appropriate argument list (actual parameters). The shared library module then RETURNs to the caller when processing is complete.

The following shared memory statements are supported:

  • SHARE - Indicates that a module is shareable.

  • SLINIT - Reinitializes the shared library.

  • ENTRY - Declares an entry point.

  • RETURN - Returns from a called procedure.

  • INSTALL - Installs the current program in the shared library and ENDs.

  • SLIST - Lists the contents of the global shared procedures library.

Shared Procedures Support

The shared procedures are then called from your program by their procedure name:

PROCEDURE_NAME (arg1,..., argn)

This statement calls a procedure named PROCEDURE_NAME with the given arguments. The argument types used must match those specified in the corresponding ENTRY statement in the shared library. For example:

0200 UPDATE(CUST,CUST$,STATUS)

Arguments passed to shared procedures may be of numeric or string type, and can be variables, literals, arrays or expressions. A shared procedure may just use the value passed or may assign a new value to the variable. This new value is passed back to the calling program. If an expression is passed to a shared library procedure by way of the argument list, it will be evaluated and it's value passed on to the shared routine. As it is the expression's value that is passed rather than a variable, there isn't a memory address for the shared procedure to update. Consequently, the expression's original value will not be changed on return from the shared procedure. For example, in the following call to a shred routine, the array element TOT[1] is an expression and is evaluated accordingly, that is, TOT[1]'a value will be passed to MYPROC rather than a memory address that the shared procedure can update:

00200 MYPROC(X,A$,TOT[1])

To get round this problem, either pass the whole array to the shared routine, or assign the element's value to a variable before the shared procedure call, that is:

00200 MYPROC(X,A$,TOT)  :or

00190 LET ELEM=TOT[1]

00200 MYPROC(X,A$,ELEM)

00190 LET TOT[1]=ELEM

Example of a Shareable U/BL program

00010 share ("TEST")

00020 entry ("PRINTIT",1000,a$,n)

00030 install (stat)

00040 if stat<>0 print "Install error ";stat

00050 end

01000 rem

01010 for i= 1 to n

01020 print a$

01030 next i

01040 a$=fill$(66)

01050 n=n*2

01060 return

09999 end

Once installed this would be called from a U/BL program as:

PRINTIT (msg$,20)

Restrictions on Shared Library programs

Programs within a shared library cannot, CHAIN, ENTER or ERASE. The SWAP command can be used in Shared Procedures and also when using Hot Keys from Shared Procedures.

If a program stops at the '*' prompt, while in a shred procedure, the user can list program lines and print or alter variables.

You will know you are in a shred procedure because when you list the code as each line number will be preceded by a '.', full stop.

User Shared Memory (UNIX Platforms Only)

The following statements can be used to access the user shared memory created by UBLMON:

SHMSIZE (N) - Returns the size, in 'N', of the user shared memory area

SHMREAD (X$) - Copies into X$ the contents of the shared memory.

SHMWRITE (X$) - Copies into shared memory the contents of X$.

Exclusive use can be achieved by using a U/BL LOCK statement:

LOCK 10, "SMEMORY",from,to


IBUILD

Format

SWAP "IBUILD"

Description

The IBUILD utility builds an index file from a sorted tag file (by key in ascending order), a sorted data file or an index file.

An argument string is sent to IBUILD via the common area, files must be open when SWAPping to IBUILD.

For a sorted data file, the start and end byte of the key must be specified. With a tag file, IBUILD assumes that the key starts at the first byte of the record, and that the record pointer associated with the key is the next four bytes.

After SWAPping to IBUILD, use the STMA 1,1 statement to check if an error occurred (0 indicates success) and STMA 1,2 to retrieve the line number. If an error does occur, block 0 of the output index if filled with nulls. This is to stop you using an index that is incorrectly built. Therefore you should back up all your files before executing IBUILD.

Errors most likely to occur:

Error Code | Message
45 | Illegal record length.
68 | Index file full.
77 | Illegal record number.
146 | Key already exists and duplicates are not allowed.
148 | File not on sector boundary.
149 | Record out of sequence.
150 | Illegal blocking factor
151 | Illegal key length.

IBUILD Argument String

Location | Size | Contents
1,4 | 4 | Channel number of the open input file.
5,8 | 4 | Byte offset to record 0 if input file.
9,12 | 4 | Maximum number of records in an input file.
13,16 | 4 | Number of bytes per record in input file. If the input file is a tag file, the number of bytes per record is the number of bytes in a tag file record plus four bytes for the pointer.
17,20 | 4 | Channel number of opened index file.
21,24 | 4 | Byte offset to record 0 of index file.
25,28 | 4 | Maximum number of blocks in index file (use INDEXCALC to calculate this).
29,32 | 4 | Number of bytes per block in index file, 512 or 2048.
33,34 | 2 | Keys per block at the specified blocking factor (use INDEXCALC).
35,36 | 2 | Flag to allow duplicate keys: 1 Allow duplicate keys. 0 Do not allow duplicate keys.
37,38 | 2 | Flag to check for deleted records. 1 Check for deleted records. 0 Do not check for deleted records.
39,40 | 2 | Total length of key field in bytes.
41,42 | 2 | Number of key fields. -1 Tag file input. -2 Index file input.
*43,44 | 2 | First byte of key (1 is the first byte of the record).
*45,46 | 2 | Last byte of key.
47,* | 4 | Next key field's descriptors. Repeat the sequence of entering the first and last byte of the key. Since you can have multiple keys, you can enter this information several times.


INDEXBLD

INDEXBLD is an interactive utility that builds or rebuilds an index file (PARAM file structure only, use LINDEXBLD for logical file database structure) from a data, tag or index file.

If using a data file, you have an option to use IBUILD or KADD to build the index file. IBUILD calls TBUILD to build a sorted tag file while KADD calls XBUILD and therefore the file will have a blocking factor of 50%.

If an error occurs while INDEXBLD is running, block 0 of the output index file will be null filled. If you are rebuilding live data, it is advisable to back up files first in case of corruption.


INDEXCALC

INDEXCALC is an interactive utility that calculates index and data file information that is needed when you run other utilities, for example, INITFILE. Calculations up to the ISAM+ limits (ISAM+ indexes allow for a maximum of 1048575 index blocks) are permissible.

The INDEXCALC utility produces the following output information:

  • Maximum number of keys per index block.

  • Number of keys per index block at specified blocking factor.

  • Number of blocks at each level in the index.

  • Number of blocks in the index.

  • Number of sectors (each 512 bytes) in the index.

  • Number of sectors in the data file.

The information needed to calculate this is:

  • Size of the index key.

  • Number of bytes in your data record.

  • Maximum number of data records.

  • A specified blocking factor as a percentage.

  • Index block size (512 or 2048 bytes).

  • Duplicate keys allowed or not.

If linked-available records are to be used, then two extra bytes must be given in response to bytes per record.

The blocking factor is used to know how many keys to fit in to the index on its creation. The lesser the percentage specified, the more room you have for future entries. Once the file has been built, the blocking factor is ignored.


INITFILE

The INITFILE utility either builds record 0 of a linked-available-record file or builds level 0 block of an index file and adds a -1 key to indicate this. It can also make a PARAM entry for itself, but only if the PARAM file already exists. The number of the last record containing data (bytes 32-35) is updated automatically, unlike in FM. All files used with the INITFILE utility must be in the PARAM file structure.

Record 0 of a Linked-available-record contains:

Bytes | Contents
0 - 1 | Status flag (always -2 for record 0).
2 - 5 | Record number of next available record (-1 if no deleted records).
6 - 9 | Record number of last number used, either last record in file or highest number record written to.
10 - | Bytes ten upwards are unused. Record 0 is always the same size as the data records.

All 2048-byte blocks must start on a 2048-block boundary, which is a multiple of four sectors. If all 2048-byte block indexes are at the start of the master file, this is not a problem.

You will need to run the INDEXCALC utility beforehand to find out the maximum number of blocks needed for an index file.


SD2UBL Utility

The SD2UBL utility is a pre-processor program, which converts SuperDOS Business BASIC source into U/BL source code. It deals with the few SuperDOS constructs that U/BL cannot directly support, such as:

  • Variables named after reserved words, for example, FOR; NEXT or FILE

  • Multiple statements per line

  • INCLUDE statements

The program is invoked from the command line by typing:

SD2UBL <inputfile><outputfile>

For example:

SD2UBL myprog.s myprog.bb

The syntax above converts the SuperDOS Business BASIC source in file myprog.s into U/BL compatible source in the file myprog.bb.


WinImport Utility

The WinImport utility imports LISTed source files to create program SAVE files.

  1. To invoke the Import utility select the Import icon from the U/BL program group on the Windows Task Bar Start menu:

The WinImport dialog box is displayed:

  2. Navigate to the directory, which contains your source files, and select the files you want to import. The files you select are displayed in the File name: field.

  3. Press the Add-> button to add these files to the Files to import section of the dialog box. These are the files which are imported to produce SAVE files:

  4. If you want to remove any of the files, highlight the files and pressing the <-Remove button.

  5. Press the GO! button to import the files. A Batch report is displayed:

This informs you of the status of your import, telling you which files were imported and the time taken.


WinPLB Utility

The Windows Program Library Builder (WinPLB) utility produces the libraries for any number of individual program SAVE files.

To invoke the WinPLB utility:

  1. Select the WinPLB icon in the U/BL program group on the start menu:

The WinPLB dialog box is displayed:

  2. Click the Browse button and select the directory, which contains the Business BASIC program files you want to place in the library.

  3. Select the files you want to place in the library from the list, by selecting the check boxes next to the chosen files (see figure above).

  4. Click on the Build U/BL Program Library button to build the library. Information regarding the build is displayed in the The Library section of the WinPLB dialog box:


U/BL Windows Enhanced Serial Support

Note: U/BL enhanced serial support only exists under the Windows NT and Windows 2000 operating systems, and is not supported under Windows 95/98.

While most new installations of U/BL for Windows use U/Gi for client access, some installations may require continued support of existing serial 'dumb terminals'.

This section covers the following topics:

  • Setting up groups of ports

  • Using a printer through a multi-serial board

  • Troubleshooting U/BL serial installations on Windows NT and Windows 2000.


Setting up groups of ports

U/BL serial support is implemented by grouping a series of serial ports together. These collections of local lines consist of a number of COM ports all running with the same configuration. The classification used to group the ports can be chosen by U/BL Administrators as required (the most obvious being geographical, for example, for printer locations, terminal type, or line configuration). However, the serial lines in the group must be consecutive ports (for example, COM1, COM2, COM3 not COM1, COM3, COM7).

Alternatively, U/BL Administrators may choose to specify and configure each serial port individually (creating groups that contain just one serial port). The definition of the serial port grouping is performed by using the Serial property page of the U/BL Control Panel:

To delete a serial port group highlight the port group and click the DEL button.

To define a serial port group click the ADD button. To modify the definitions associated with a particular group, highlight the group name you want to modify and click the EDIT button. In both these cases the Serial ports setup dialog box is displayed:

The Serial ports setup dialog is where the configuration for a group of serial lines is made. Ranges of serial ports can be specified for each group, and an environment specified. This environment can be overridden by those settings in the user account, but it always takes precedence over the global environment.

To enable a U/BL Administrator to define the settings to be used for the lines in the current group, click the Serial button. The Serial settings dialog box is displayed:

Serial settings (baud rate, parity, and so on) can be specified for each group of serial ports. Whenever the U/BL server listens on a serial line, it first ensures that the lines' configuration matches the requested settings (adjusting the lines current state where necessary).

Note: There is no synchronization between the line settings made in U/BL's Control Panel applet and the Windows settings.


Using a printer through a multi-serial board

If using a serial printer from U/BL through certain types of serial board, for example, some DigiBoards, the printer may not work. This is because Windows grabs the printer port, but does not set the comm settings until it is first used. When U/BL tries to use the port, it cannot set the settings as Windows also has it open.

To resolve this, a utility called OpenPrt is provided. This uses the Windows Printer System to open the port. On some printer drivers, it may be necessary to print something in order to set the comm port settings.

OpenPrt printer utility

This program takes the name of a serial port from the command line, and opens the printer to try to get Windows to set the port settings. Optionally, it prints a blank page, as this might be necessary to cause the printer driver to action. It can also print the contents of a text file in a rectangle.

Note: A Windows printer must be set up on the port in order for this utility to work.

Usage

This utility is designed to be called from the U/BL startup batch file startupNT.bat, in order to correctly configure serial ports connected to printers.

Command line

OpenPrt <comport> [-p] [-f filename]

Switches

<comport> | Case insensitive com port name, for example, com2. A colon is appended to the name if one is not provided.
-p | Prints a blank page. This may be necessary on some printer drivers.
-f <file> | Prints the contents of text file <file> to the printer in a bounded rectangle.

Note: This utility is provided for the users convenience, and is not supported by Transoft.


Troubleshooting U/BL Serial Installations on Windows NT and Windows 2000

The following steps can be followed to resolve problems using U/BL's serial support under Windows NT and Windows 2000:

Logging in

  1. Shut down the U/BL server, and use Hyperterminal or similar to test communications between the PC and the terminal. U/BL will not work until the serial line does. Close down Hyperterminal before proceeding.

  2. Ensure that the serial settings on the U/BL control panel and the terminal match.

  3. Ensure that the Line Terminator character is set to the correct character. This is normally CR.

  4. Restart the server.

  5. Press RETURN on the terminal to bring up the login prompt.

  6. Check the event log, applications section (from the File menu) for any messages.

Screen display problems

  1. Ensure that the BBTERM is the correct one for the terminal in use. The same TDF files can be used on both UNIX and Windows U/BL platforms.

  2. If the terminal supports multiple terminal emulations, ensure it is in the correct mode.

  3. If screen corruption occurs when large amount of text is sent to the terminal, ensure handshaking (flow control) is set on both the U/BL serial settings and the terminal, and ensure that the requisite cabling is in use.

BBTTYS

Ensure:

  1. That BBTTYS is set in the environment.

  2. That the com port line is in upper case. (e.g. COM3)

  3. That the sys(4) value is not in use by another process (!)

  4. That UBLNTCOMMPORT is set in the U/BL processes environment. This is an automatically set environment variable used internally by U/BL. This should contain the number of the port, for example, '15' for COM15.

DIM A$[100]

$getenv "UBLNTCOMMPORT",a$

This must match the value in the BBTTYS file, minus the COM header.


U/SQL Embedded Report Writer

U/BL includes the Embedded U/SQL Report Writer. This product is a query language, which allows users to retrieve information from a variety of file and database structures. The Embedded U/SQL Report Writer within U/BL allows the user to produce U/SQL queries using a single line of code in a U/BL program.

Several example programs using this utility are provided in the eusql sub-directory within the release. A brief description of these programs is provided below:

demo1.ubl | This is a U/BL program which demonstrates a simple U/SQL Embedded Report Writer query.
demo2.ubl | This program demonstrates another simple U/SQL Embedded Report Writer query, but this time the report is sent to the printer.
demo3.ubl | This U/BL program uses a U/SQL Embedded Report Writer query to read a customer database and then show a list of customer names in a U/BL pull down menu. You can then select one of the customers as input to a further query.
demo4.ubl | This program demonstrates a simple, report-based query.
oneline.ubl | This is an example of a U/BL one line report program.
runquery.ubl | This program uses the uxgetb.slib shared library procedure (so uxgetq.slib must be installed in the shared library before RUNning this program - see below). The runquery.ubl program passes a query name to the uxgetq.slib shared library procedure, and the procedure returns the query and its set$ string.
uxgetq.slib | This is a U/BL shared library procedure which is used by the runquery.ubl demonstration program. It must be installed in the shared procedure library before the runquery.ubl program is RUN.


Large File Support

U/BL revisions 5.00 and above provide support for large files, that is, files larger than 2GB. 2GB was previously the limit on file size imposed by the use of 32-bit file access. U/BL 5.00 makes use of 64 bit file access system calls where these are provided by the operating system, U/BL 5.00 does not provide support for large files if the 64 bit file access system calls are not provided by the operating system. The BBLARGEFILES environment variable must be set to Y to enable support for large files. In addition the BBPRECISION environment variable must be set to 8.

The support for files larger than 2GB in U/BL has been implemented in a way designed to minimise required changes to data structures and program code. In the case of files that will not exceed 2GB, there are no required changes to data structures or file access code. Where files may exceed 2GB in size, the main requirement is that these files must be separate physical files, not sub-files. If files exceed 2GB in size, the format of information returned by various statements that give file status information, such as FCB$, will be changed to accommodate larger numbers.

This section discusses the following topics:

  • Supported Platforms

  • Environment Variables

  • Modified Statements

  • U/BL Runtime

  • File Structures

  • Index Files

  • Super DOS Data Files.


Supported Platforms

U/BL only provides Large File Support (access to files larger than 2GB) on platforms which provide the 64-bit file access system calls.

The following platforms are supported:

  • Windows NT SP 4

  • Windows 2000

  • Windows XP

  • Sun Solaris 2.6

  • AIX 4.3.3

  • OpenUnix 8

  • RedHat Linux 7.1

  • Caldera Open Linux 3.1

  • HP/UX 11

  • Unixware 7.1.1 and HP/UX 10.2 – will both support access to large files on a local disk, not via NFS as the Operating System uses NFS Version 2 protocol which does not support large file access.


Environment Variables

In order to use U/BL's Large File Support (LFS) the following environment variables must be set as follows:

BBLARGEFILES=Y | The BBLARGEFILES environment variable must be set in the environment when the U/BL runtime is started as well as when U/BL is started. The default value for BBLARGEFILES is N.
BBPRECISION=8 | If the BBLARGEFILES environment variable is set to Y, then the BBPRECISION environment variable must be set to 8 when U/BL is started to enable the use of 8 byte numeric values. If BBLARGEFILES is set to Y, then it will not be possible to change the setting of BBPRECISION dynamically during a U/BL session using the $PUTENV statement.


Modified Statements

U/BL revisions 5.00 and above provide Large File Support. This has required several U/BL statements to be modified.

The SYS(30) statement has been modified to indicate whether U/BL has been invoked with support for large files. If bit 13 (4096) is set then U/BL is running on a platform that supports large files and BBLARGEFILES=Y and BBPRECISION=8. This allows the U/BL programmer to write code for LFS and non-LFS operation.

For example:

IF AND(SYS(30),4096) THEN

LFS CODE….

ELSE

non-LFS CODE….

END IF

The following additional statements have also been modified to facilitate Large File Support:

STMC 4, STMC 33, STMC 51

STME 5, STME 6, STME 7

CHFREEZE

FCB$

INQUIRE.


U/BL Runtime

The U/BL Runtime is used by both U/BL and U/SQL Client Server for BB-ISAM to store locking information. U/SQL Client Server 3.20 for BB-ISAM supports Large File Access.

If large files (that is, files larger than 2GB) are used then the structure of the runtime must be modified to allow file positions to be stored in 8 bytes rather than 4 bytes.

The following matrix shows which versions of U/BL and U/SQL Client Server for BB-ISAM will interface with which versions of the U/BL runtime:

LARGE FILES NOT USED | U/BL 2.xx runtime | U/BL 5.00 runtime
U/BL 2.xx | Y | Y
U/SQL Client Server 3.00+ (< 3.20) | Y | Y
U/BL 5.00+ | Y | Y
U/SQL Client Server 3.20+ | Y | Y
LARGE FILES USED | U/BL 2.xx runtime | U/BL 5.00 runtime
U/BL 2.xx | N | N
U/SQL Client Server 3.00+ (< 3.20) | N | N
U/BL 5.00+ | N | Y
U/SQL Client Server (new version) | N | Y

If the BBLARGEFILES environment variable is not set to Y when the U/BL runtime is started, then the structure of the U/BL 5.00 runtime will be identical to that of the U/BL 2.40 runtime.

The B32 Lock Manager does not support the use of large files (files larger than 2GB).


File Structures

U/BL Rev 5.00 and above provide support for large files (that is, support for files larger then 2GB in size). The implementation of this functionality minimises required changes to existing file structures. This means that the byte offset of sub-files in PARAM and '.VL' control files will still be stored in 4 bytes.

Therefore, if a sub-file is likely to exceed 4GB in size, so that the byte offset to the next sub-file will exceed the value that can be stored in 4 bytes, the sub-file that will exceed 4GB must be extracted into a separate physical file. To aid this extraction the filesplitter utility has been provided.

The maximum number of records will also still be held in 4 bytes in the file control structures, PARAM, '.VL' and record zero. This means that the maximum number of records will be limited to approximately 4 billion (2^32-1).

EFS was introduced in U/BL to allow Indices in sub-files to be extended without having to re-build the physical file. EFS will not be applicable to files larger than the current 2GB limit.


Index Files

The maximum size of an Index file is determined by:

  • The Block Size, which may be 512 bytes or 2048 bytes, and

  • The maximum number of blocks, which is stored in 2 bytes by default, but may be stored in 3 bytes if ISAM+ format is used.

Taking into account this information, the maximum size of an index file is:

512 byte index, standard format | maximum size is approximately 33 MB
2048 byte index, standard format | maximum size is approximately 134 MB
2048 byte index, ISAM+ format | maximum size is approximately 34GB.


SuperDOS Data Files

Control information for SuperDOS data files is held in a 512 byte FCB block. The size of the file in 512 byte blocks and the maximum number of records are each held in the FCB block in 3 bytes.

This imposes a limit of approximately 16.7 million (2^24-1) on the number of records or number of blocks and a file size limit of approximately 16.7 million multiplied by 512 bytes, approximately 8.5GB (2^24-1*512).

Two bytes of the FCB block are used so that the maximum number of records / blocks and the size of the file may both be stored in 4 bytes. File conversion is not required as the extra byte will only be used if the BBLARGEFILES environment variable is set to Y and the file exceeds 2GB in size.

The maximum number of records / blocks in a SuperDOS data file will be approximately 4 billion (2^32-1).

The theoretical maximum file size of a data file will be approximately 2,199GB, (4 billion multiplied by 512 bytes, ((2^32-1)*512)) or 4 billion multiplied by the record size, whichever value is lower.


Environment Variables Management

Environment Variables specify how U/BL operates in the particular environment in which you are running, be it UNIX or Windows NT.

The majority of the environment variables start with the prefix BB, for example, BBTERM, BBPROGS and so on. There are various groups of environment variables that define:

  • The configuration of U/BL, that is, the number of lines, program code and data memory size, the number of variables allowed and so on.

  • The Banner file which controls U/BL licensing.

  • The type of terminal you are using.

  • The directory structure you are working in, that is, where the programs and data files reside.

  • The directing of print files to various printers.

These are just some of the major categories.

BBENV file

The environment variable settings are usually assigned in an ASCII file, called BBENV, which can be modified by any editor. The environment variable BBENV can be specified to indicate to U/BL where the BBENV file is located.


BB2048

Description

The BB2048 environment variable provides complete buffering of each 2048 index block when performing KNEXT and KPREV commands. This is achieved by the reDIMensioning of the buffer string, when necessary, up to a maximum size of 2592 bytes. This provides enough storage space for the 2048 byte index block and its control information.

This feature emulates the handling of 512 byte index blocks by buffering the current index block. The buffering of the current index block means that any KNEXT or KPREV statements will not reflect the true data as it is held on disk. For example, if process A performs a KFIND on a key, the contents of A's buffer will be the index block which contains that key. If process B performs a KDEL on the key which immediately follows A's key, process A will still "pick up" that key when it does a KNEXT, as it is still in A's buffer.

Process A is working from its buffer and does not, therefore, reflect the situation as it is on the disk, that is, the key that it finds in its buffer on a KNEXT has actually been deleted by process B's KDEL statement. This emulates Data General Business BASIC.

The Data General Business BASIC implementation of K-operations on 2048 byte index blocks did reflect the true, disk state of the index.

Setting BB2048 to RESIZE means that any buffer strings that are used in K-statements such as KFIND, KNEXT and KPREV, will be automatically re-DIMensioned to 2592 bytes when necessary. This allows a complete 2048 byte index block and its control information to be read into the buffer and any subsequent KNEXTs or KPREVs will operate on that buffer.

For this reason this environment variable should not be used in those applications where the key returned from a KNEXT or KPREV statement must reflect the keys as they are held on disk.

BB2048 does provide considerable performance improvements when performing a number of KNEXT or KPREV statements. It should be set as follows:

BB2048=RESIZE

The settings BB2048=COMP and BB2048=NOCOMP are now redundant, since the general handling of 2048 KNEXT and KPREV statements has been improved.

This environment variable cannot be changed by a $PUTENV statement.

Example

BB2048=RESIZE


BB30FF

Description

The BB30FF environment variable is used to inhibit the erase to end of screen functionality of PRINT "<30>FF".

On later Data General terminals, this sequence performs an erase unprotected function. This is not supported by Basic, but by setting BB30FF=N in your environment it will work on a Data General D-series terminal provided that Basic's windows are not being used.

This environment variable cannot be changed by a $PUTENV statement.

Example

BB30FF=N


BBASCX

Description

The BBASCX environment variable performs the same function as the "-x" switch on Data General's Business BASIC for UNIX. It causes the ASC statement to perform as though it were an $ASX. To switch this feature on, set BBASCX to "Y". The default setting is "N".

This environment variable cannot be changed by a $PUTENV statement.

Example

BBASCX=Y


BBATINPWAIT

Description

The BBATINPWAIT environment variable controls the behavior of the @INPUT statement when using an unpend table.

BBATINPWAIT only modifies the action of @INPUT when an unpend table is in use, that is, bit 4 of the @INPUT flags has been set by an @DESC statement.

By default, when on an @INPUT statement, U/BL cannot distinguish between two unpend sequences if one sequence starts with the same keys that make up the other sequence. For example, if the unpend table defines the two sequences E and ESC-Q, U/BL cannot normally tell them apart. It will recognize them both as the ESC sequence, the second being followed by the Q character.

To resolve this problem, U/BL must wait after receiving the first character of any unpend sequence to see if any other character is following. If no characters follow, the sequence should be immediately compared with the unpend table, otherwise all the pending keys must be received before the sequence can be matched.

To enable this wait, BBATINPWAIT=Y must be set in your environment (prior to invoking U/BL, as BBATINPWAIT cannot be changed by a $PUTENV statement).

Example

For the program:

00010 DIM UNPND_TBL$[28],ENV$[10]

  00020 REM Set up @INPUT environment to the normal default

  00030 LET ENV$="<0><0>,-<127><5><8><12><0><0>"

  00040 REM Now enable unpend table

  00050 LET ENV$[1,2]=CHR$(OR(ASC(ENV$[1,2]),16),2)

  00060 REM UNPND_TBL$ set up to recognize following characters;

  00070 REM Character-Sequence key's Function

  00080 REM <13> Unpend #1

  00090 REM <10> Unpend #2

  00100 REM <27> Unpend #3

  00110 REM <11> Unpend #4

  00120 REM <127> Backspace

  00130 REM <27>Q Insert

  00140 REM <8> Left Arrow

  00150 REM <12> Right Arrow

  00160 REM <27>W Delete

  00170 LET UNPND_TBL$="<11><0><2> <13><0><10><0><27><0><11><0>"

  00180 LET UNPND_TBL$[0]="<127><0><27>Q<8><0><12><0><27>W<0><0><0><0>"

  :

  : Main body of program

  :

  00800 @INPUT(START,NFIELDS,INPUT_BUFFER$)

  :

  : Rest of program

  :

the input to the @INPUT of 'A,B,D,<8>,<27>Q,C,<NL>' will cause the following (assuming each ',' in the input stream represents 1 keypress):

BBATINPWAIT=N or is not set
(the default case)

U/BL recognizes the <27> as unpend #3 and terminates the @INPUT following this character, leaving INPUT_BUFFER$ unchanged.

BBATINPWAIT=Y

U/BL recognizes the <27> as part of an unpend sequence so waits to see if another character is present. When it receives the Q it waits for any following character.

As no further character is generated by the current keypress, U/BL looks at the unpend table to match the <27>Q. This causes U/BL to insert the next character ('C') at the current cursor position.

The end result is that 'ABCD' is returned from the @INPUT following the <NL>.

Under SuperDOS Business BASIC, this key mapping is performed in hardware so no specific software settings are needed to emulate this functionality. However as U/BL has to implement this feature in software, some limitations apply.

With BBATINPWAIT set to Y, holding down a special key (for example left-arrow) causes the key to only be recognized twice, once when the key is initially pressed and once when it is released. This is caused by U/BL being unable to wait for less than 1/10 of a second between each key press (the actual delay is set by the environment variable BBIKEYWAIT) which is more than the delay between the keyboard's auto-repeat logic.

See also

@DESC

@INPUT

BBIKEYWAIT


BBATINPYR

Description

The BBATINPYR environment variable controls how many digits the SuperDOS @BLANK; @PRINT and @INPUT commands will expect for a type 'J' field, when a year is being processed. By default, this is two digits if date windowing is being used (see the documentation for the BBDATEWINDOW and BBJULIANFLAGS environment variables) or three digits if not.

Valid values for the BBATINPYR environment variable are 2, 3 or 4.

2 | Specifies whether years are to be inputted in windowed form (2 digits)
3 | Specifies a year offset form (XXX years from 1900)
4 | Specifies an absolute year value (CCYY).

Previous revisions of U/BL; UBB and SuperDOS Business BASIC itself only ever supported two digit years. If you are using other settings for BBATINPYR remember to ensure that your screen design can cope with the extra characters that are displayed.

This environment variable can be changed by a $PUTENV statement.

Example

BBATINPYR=4

This ensures that @INPUT and @PRINT expect a 4 digit date whenever a 'J' type field is being processed.


BBATTRIBORDER

Description

The BBATTRIBORDER environment variable dictates the order of bytes used by the SLOAD and SSTORE statements.

Each character's value and its attribute, for example, underscored, are held in a pair of bytes. BBATTRIBORDER can be used to define the order in which these two bytes are held. If it is set to C, then the character's value will come first. If it is set to A, then the first byte of the pair will hold the character's attribute.

The default action is character first for Windows and attribute first for UNIX. This is to keep the SSTORE command compatible with previous versions of Basic.

This environment variable can be changed by a $PUTENV statement.

Example

BBATTRIBORDER=C | Windows based system setting
BBATTRIBORDER=A | UNIX based system setting.


BBAUTOBAN

Description

If the BBAUTOBAN environment variable is set to a number of seconds, the Transoft Licence banner screen will automatically unpend after that number of seconds has elapsed. For example, if the number of seconds is less than ten, or if BBAUTOBAN is set to Y, the licence banner will unpend ten seconds after U/BL has been invoked.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBAUTOBAN=60

See also

BBUNPEND


BBBYE

Description

If the BBBYE environment variable is set, then when the '*' prompt is reached the product will automatically BYE off.

This environment variable can be changed by a $PUTENV statement.

Example

BBBYE=Y


BBCACHE

Description

The BBCACHE environment variable is one of a group of environment variables which can be used to configure the U/BL product. It defines the size of the index cache in kilobytes.

The use of a write-through index cache can improve considerably the performance of index based activities. For a single user, the cache size is set to 5kb. If not enough memory is available to support this extra 5kb, set BBCACHE to 0 or to a value less than 5kb. The optimum value is around 20kb.

It is NOT RECOMMENDED that the index cache is generally used in NET mode, as there is no guarantee that file index activity will be synchronized. If you are producing batch reports, where there is no updating of files, or where files are OPENed in exclusive mode, then the index cache may be used. The default under NET is BBCACHE=0.

Under Windows, if the same index is OPENed on two different channels, one for WRITEs and the other for READs, then the index cache should NOT be used and BBCACHE should be set to 0.

This index cache can be used with or without a Windows cache such as SMARTDRV.SYS.

If this environment variable's setting is changed, then the change must be made before U/BL is invoked. This environment variable cannot be changed by a $PUTENV statement.

Example

BBCACHE=15

defines the size of the index cache as 15 kilobytes.


BBCASE

Description

By default U/BL tries to OPEN data files in UPPERCASE. The BBCASE environment variable can be set to DL to specify that the data files are in LOWERCASE. This applies equally to files being created or READ. The directory paths can remain in mixed case.

If an absolute path, beginning with '!', for example, !/dir1/dir2/FILENAME, or an UNIX native file path, for example, /dir1/dir2/FILENAME, is specified then BBCASE is never applied.

This environment variable can be changed by a $PUTENV statement.

Example

BBCASE=DL


BBCHAN

Description

The BBCHAN environment variable is one of a group used to configure the U/BL product. It determines the number of channels available to the program.

Note: In a multi-user environment, for example, under UNIX or Windows NT, each user can have a different configuration, but the product is unlikely to be used in this way.

If this environment variable's setting is changed, then the change must be made before U/BL is invoked.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBCHAN=60

defines the number of channels as 60.


BBCHAR

Description

The BBCHAR environment variable sets certain terminal characteristics that are not included in the Terminal Definition File. Its operation is based on Data General's AOS/VS 'CHARACTERISTICS' command.

Currently only two characteristics may be set:

8BT | Allows 8 bit character input. This performs the same function as setting the BBSTRIP environment variable to 'N'.
FKT | Allows function keys to be treated as delimiters. This enables function keys to unpend input and be treated as one entity. For example: INPUT USING "",A$,B$ If <F1> is used to unpend the INPUT: A$ will contain the inputted string. B$ will contain the unpend character, in this case "<30>q".

Unless specified by BBCHAR, both of these characteristics are switched off (8BT will effectively be on if BBSTRIP is set to 'N', however).

Note: If BBSTRIP is set to 'Y' and BBCHAR includes 8BT the effect is like having BBSTRIP=N, that is, BBCHAR has precedence over BBSTRIP.

To switch the characteristics on, they must be included in the string BBCHAR equates to, separated by forward slashes '/'.

If an attempt is made to use an invalid setting for BBCHAR, Basic will display the following warning message when it is invoked (Basic will start up as normal after displaying the message):

WARNING: BBCHAR invalid (<invalid setting>)

This environment variable cannot be changed by a $PUTENV statement.

Example

BBCHAR=FKT | Sets second characteristic
BBCHAR=/FKT | Sets second characteristic
BBCHAR=8BT | Sets first characteristic
BBCHAR=8BT/FKT | Sets both characteristics

See also

BBSTRIP


BBCHECKPATH

Description

If the BBCHECKPATH environment variable is set to Y, the CHECK statement will return the file's full pathname in its result string. If the result string is not DIMensioned large enough to receive the full pathname, then only the file name will be returned.

The full pathname will be returned if BBCHECKPATH is set to Y and if CHECK finds the file in the current directory or in a directory specified by the environment variables BBSEARCH, BBSEARCH01-20 and BBPATH.

Example

BBCHECKPATH=Y

See also

CHECK


BBCLOSEALL

Description

If the BBCLOSEALL environment variable is set to "Y" (the default setting), a CLOSE FILE[16] statement will CLOSE all OPEN files. If set to "N", the statement will be ignored.

This environment variable is necessary because Data General's Business BASIC is inconsistent over different revisions, in respect of the action of a CLOSE FILE[16] statement.

This environment variable can be changed by a $PUTENV statement.

Example

BBCLOSEALL=N


BBCLS132

Description

If the BBCLS132 environment variable is set to "N", then U/BL will not clear the screen on a PRINT @(-80) or a PRINT @(-132) statement.

Note: Some hardware may force the screen to be cleared when changing the number of columns, in which case BBCLS132 will be ignored.

Example

BBCLS132=N


BBCOMMENT

Description

If the BBCOMMENT environment variable is set to "Y", program line comments will be preserved when the program is SAVEd or REPLACEd.

If the program line is a GOSUB or GOTO, and the line referenced has a comment, then this comment will override the program lines. If the referenced line's comment is removed, then the original comment will be restored. More memory will be required to hold these comments. Once the comments have been SAVEd there is no way of removing them.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBCOMMENT=Y

* 10 print "This is the Heading" : Print the Heading line.

* list

00010 PRINT "This is the Heading" : PRINT THE HEADING LINE.


BBCOMMON

Description

The BBCOMMON environment variable defines the size of the common block. The default size of the common block is 512 bytes. The BBCOMMON environment variable can be used to extend it from 512 bytes to a maximum of 2048 bytes.

Note: The size of the common block specified by this environment variable cannot be increased from its original setting (that it was set to when U/BL was invoked), via the $PUTENV statement.

Example

BBCOMMON=2048

See also

BLOCK_READ

BLOCK_WRITE


BBCONMAP

Description

The BBCONMAP environment variable defines the terminal printer in BBMAPFILE. U/BL's printer controls support internal data in a portable manner as 7 bit characters, and allow the use of 8 bit printers.

A printer mapping file, defined by the BBMAPFILE environment variable , containing "from-to" character mappings is created containing a number of sections, one for each named printer. The end of each printer's mapping is denoted by the "/" character.

When a printer is opened via an OPEN FILE statement, the printer name, less the "@" or "$", is looked for in the BBMAPFILE. If found then the print mapping for that printer is installed and the appropriate 7 bit to 8 bit maps used.

When printing through the terminal, it is also possible to define printer mapping, by stating which printer in the BBMAPFILE is attached to the particular terminal using the environment variable BBCONMAP. For example, BBCONMAP=vt220.

This environment variable can be changed by a $PUTENV statement.

Example

BBMAPFILE=PRINTMAP

BBCONMAP=vt220

PRINTMAP contains:

LPT1

  5e,c8

  6f,d7

  /

  vt220

  5b,b9

  5c,d4

  /

The above entries could be for an IBM printer (LPT1) and a VT220 print-pass-through (vt220).

Note: No blank lines or comments are allowed in the BBMAPFILE. The only valid entries are a printer name, a pair of comma separated hexadecimal numbers, or a definition terminating '/' character.

If the BBMAPFILE is illegal, it will be ignored, and no error will be reported by U/BL.

See also

BBMAPFILE

BBSPOOL


BBCONSOLIDATEDLOG

Description

If this environment variable is set then a log of all changes to the U/BL job table is written to the file specified by the environment variable.

This environment variable should only be set when attempting to find a possible problem, it should not be set for normal running.

This environment variable cannot be changed using the $PUTENV command.

Example

BBCONSOLIDATEDLOG=<path name of log file>


BBDATEWINDOW

Description

The BBDATEWINDOW environment variable enables the user to select a 100 year date windowing facility for the date related Business BASIC statements, STMA 11; STMA 12; @INPUT type 'J' fields; FROMJULIAN; TOJULIAN; $DATE$ and $VDATE).

Date windowing is a standard method to allow 2 digits to represent a range of years. It is much more flexible than assuming that 2 digits represent a year in the current century. This technique allows a range of 100 years to be represented in 2 digits, and is based on the fact that given the starting date for the range of years being encoded, it is possible to infer what year any two digit number represents. This is done by comparing the two digits with the lower 2 digits of the starting year. For any starting year, <CC><YY>, the windowed range of years will be <CC><YY> to <CC+1><YY-1>. This fact allows the inference to be made that any 2 digit number less that <YY> must fall in the century of where the end of the windowed range falls (<CC+1>). Similarly, for values equal to or greater than <YY>, the century must be that where the start date falls (<CC>).

For example, consider the windowed range of 100 years starting at 1968. This equates to the years 1968 - 2067. Any 2 digit number, XX, less than 68 must therefore represent a value in the 21st century (20XX) as there would be no relevant 20th century date in the windowed range. Similarly, any 2 digit value greater than 67 must fall in the 20th century (19XX) as there would be no corresponding value in the 21st century which would fall in the range we are representing.

When date windowing is in operation, the Business BASIC statements STMA 11/12; @INPUT type 'J' fields; FROM/TOJULIAN;. $DATE$ and $VDATE will expect or return 2 digit values representing a year within 100 years of the start of the date window. The starting point for the window is defined by the setting of BBDATEWINDOW which is set to the first valid year in the windowed range.

Setting BBDATEWINDOW automatically selects date windowing using the specified base date. However, date windowing can also be selected if BBDATEWINDOW is not set. Under these circumstances, the value of the environment variable defaults to 1968. This allows U/BL to automatically use the same windowing algorithm as SuperDOS Business BASIC. Under SuperDOS, the base date is always 1968 rather than the variable value supported by U/BL (via this environment variable). Apart from specifically setting BBDATEWINDOW, date windowing may be selected by any one of the BBJULIANFLAGS; BBSDOSDATE or BBEXTENSION environment variables. If no date windowing is selected, there is no default value for this environment variable.

This environment variable can be changed by a $PUTENV statement.

Example

BBDATEWINDOW=1968

This makes U/BL imply that any 2 digit year, 'YY' less than 68 represents the year 20YY while any equal or larger value represents 19YY.


BBDEBUG

Description

The BBDEBUG environment variable determines whether debugging is available to the user. The default is N, and this means that it is not possible to LIST, change variables or enter source code. If source is attempted to be LISTed then the product responds with:

  What?

To allow debugging to take place set BBDEBUG=Y.

If the current value of the BBKEY environment variable does not match the value when the program being LISTed was originally SAVEd then, again, even with BBDEBUG=Y, the product will respond with:

  What?

This environment variable can be changed by a $PUTENV statement.

Example

BBDEBUG=Y

See also

BBKEY


BBDEFACL

Description

The BBDEFACL environment variable sets the default access control list for use when creating files. The UNIX shell command umask 000 must be actioned before the product is invoked with this environment variable set.

Note: The file's type, for example, d for a directory, c for a character device, cannot be set using this method.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDEFACL=rwx-rw-rw-


BBDELAY

Description

Operating system limitations under both UNIX and DOS mean that U/BL has to round the DELAY statement's time period up to the next full second.

If the BBDELAY environment variable is set, then a DELAY of less than 0.5 second will return immediately. If BBDELAY isn't set then the minimum DELAY period is one second.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDELAY=Y

See also

DELAY


BBDELREC

Description

If the BBDELREC environment variable is set to Y, a check will be made to see if the record has already been deleted when performing a DELREC statement. The default setting is N.

If the environment variable BBEXTENSION is not set, that is, Data General Business BASIC emulation is being used, then if the first two bytes of the record are less than or equal to zero, and the next four bytes are non-zero, then the record has been deleted already and an error 81 (Illegal Status) will be generated.

If the environment variable BBEXTENSION has been set to include B32, then the first six bytes of the record are checked. If the first two bytes are zero, and the next four are non-zero, then the record has already been deleted and an error 81 (Illegal Status) is generated.

If the environment variable BBEXTENSION has been set to include SDOS, then BBDELREC is redundant, since the first byte of the record is always checked to see that it is not -123. If the first byte is -123, then an error -135 (Record Cannot be Deleted) will be generated.

So that the above checks will always work, the first six bytes of a record are set to zero after a GETREC (providing that BBEXTENSION has not been set to include SDOS).

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDELREC=Y


BBDEVICE

Description

The BBDEVICE environment variable defines the access method for device names. In U/BL, a file is recognized as a device if its filename starts with a '$' or an '@' symbol. Additionally, under Windows, the device files LPTx, COMx, AUX and PRN are also regarded as device files by U/BL. When you directly OPEN a file the device recognition is straight forward, it is just a matter of checking the file's name to see if it matches any of the above criteria. When you are OPENing a link to the file, the recognition is a little more complicated.

The BBDEVICE environment variable allows the user to explicitly tell U/BL whether or not the linkname alone, or either the linkname or its resolution indicate if the file represents a device. If BBDEVICE is not set, the original logic for device recognition is employed. If BBDEVICE is set to 'LINK' (or 'L'), only the filename of the link determines if the file is a device. For example, with BBDEVICE=L the file $LINK->PRINTER would be recognized as a device while LINK->$PRINTER would not.

The other alternative setting for BBDEVICE is BBDEVICE=ALL (or 'A'). This causes the file to be regarded as a device if either the linkname or its resolution can be recognized as such. Under this setting, both of the links in the above example would be regarded as device files whilst LINK->PRINTER would not.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDEVICE=ALL


BBDGTINPUT

Description

The BBDGTINPUT environment variable forces the TINPUT statement to behave as Data General Business BASIC's does. If this environment variable is set to Y, the timer will be reset after each keypress.

This environment variable can be changed by a $PUTENV statement.

Example

BBDGTINPUT=Y

See also

TINPUT


BBDOSSLOCK

Description

The SLOCK statement uses a local table to store information on outstanding SLOCKs. The BBDOSSLOCK environment variable controls the number of SLOCKs which can be in use concurrently by a particular workstation. The default number of SLOCKs is 30, and this should be sufficient for most applications. If you are SLOCKing a range of records, each record in the range requires one table entry.

Technical limitations imposed by Windows based operating systems mean that it is not possible to support the READLOCK statement. A READLOCK statement will be executed, but it will have no effect.

Note: Any I/O to a locked record will block, even when using the READLOCK statement, until the conflicting lock is removed by the appropriate workstation.

There are several error numbers and messages associated with the SLOCK statement:

9456 | Internal Slock table full - increase BBDOSSLOCK
9457 | Internal Slock error deleting on a channel
9458 | Internal Slock error unwinding slocks
9459 | Internal Slock error deleting a slock
9460 | Internal Slock error allocating slocks - decrease BBDOSSLOCK.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDOSSLOCK=50

See also

BBSLOCK


BBDUPSYS4

Description

Setting the BBDUPSYS4 environment variable to Y allows duplicate SYS(4) values. It should be used together with the BBTTYS environment variable if there is a need for more than one process to be running on the same BBTTYS line.

If, for example, the file specified by BBTTYS contains the following entry:

/dev/ttyi08 8

this gives the terminal on line /dev/ttyi08 a SYS(4) value of 8. When the product is started up on that terminal, any subsequent sessions started by, for example, entering !ubl at the '*' prompt, will also have a SYS(4) value of 8.

If BBDUPSYS4 is not set, or if it is set to N, then any attempt to bring up subsequent sessions will result in an "Illegal SYS(4) value" message.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBDUPSYS4=Y

See also

BBNXTFREE

BBSYS4INC

BBTTYNO

BBTTYS


BBEDIT

Description

Typing EDIT at the U/BL * prompt will invoke an external editor with a listing of the current program. When the editing session is finished, the program will be re-ENTERed if the code has been changed.

By default U/BL will invoke vi on a UNIX system and EDIT on a Windows system. You can specify an alternative editor by setting the environment variable BBEDIT to the name of the editor's executable file.

Unless the editor is in the current directory, or in a directory in your path, then the BBEDIT environment variable must specify the full path name of the editor.

This environment variable can be changed by a $PUTENV statement.

Example

UNIX - use emacs as an alternative to vi:

BBEDIT=/usr/bin/emacs

Windows - use EDLIN as an alternative to EDIT:

BBEDIT=C:\DOS\EDLIN


BBENV

Description

The BBENV environment variable defines the file, usually called BBENV, that contains the rest of the environment variables.

Any operating system variables consisting of letters, digits and underscores, can be used on the right hand side of any of the assignments in BBENV. For example, the following could be an entry in a UNIX based BBENV:

BBPATH=$HOME/bin:/u/progs

More than one operating system environment variable per line is allowed. Note that you cannot use $PUTENV to change an environment variable which has been set as an operating system variable. The environment variable will usually be placed in the logon file for each user, that is, in '.profile' under UNIX and AUTOEXEC.BAT under Windows.

There are limits to the amount of memory available for the BBENV file. Under Windows the limit is 768 bytes, and under UNIX the limit is 1024 bytes. These figures are the maximum sizes for BBENV files. Anything after the maximum number of bytes will be ignored, but a warning message will be displayed when U/BL is invoked.

These figures do not include any operating system environment variables, so if the BBENV file is approaching its maximum size, "global" environment variables could be set up as operating system environment variables in the system start-up routines, and the BBENV file reserved for user specific environments.

Any comments in BBENV files will be ignored, and will not form part of the total number of bytes.

This environment variable cannot be changed by a $PUTENV statement.

Example

Under Windows

BBENV=\USER\UBL\BBENV

Under UNIX

BBENV=/user/ubl/BBENV


BBENVMOD

Description

The BBENVMOD environment variable


BBEOF

Description

The BBEOF environment variable is used to override the default action on detecting the end of file on the standard input redirected from a file. This action is normally set so that the product automatically BYEs off. By setting BBEOF=N, the product will not BYE off on detecting the end of file on the standard input.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBEOF=N

See also

BBTTYEOF


BBERM

Description

The BBERM environment variable identifies a file that is equivalent to Data General Business BASIC's BASIC.ER file.

If an invalid directory or file is used in setting BBERM, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBERM contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBERM=\USER\UBL\BASIC.ER

Under UNIX

BBERM=/user/ubl/ERRFIL

See also

BBUBBERM


BBEXCL

Description

The BBEXCL environment variable, which by default is BBEXCL=Y, determines whether the shared facilities maintain details of each file opened by each job. The reason for their inclusion is that UNIX does not support the knowledge that a file may have been opened in shared mode so it is possible for another job to then open the same file in exclusive mode, resulting in possible corruptions.

Of course, in general most U/BL systems are not written like this. If this is the case, then by setting the environment variable BBEXCL=N, the file details will not be maintained in the shared facilities and this will result in faster file opening.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBEXCL=N


BBEXECRETURN

Description

The BBEXECRETURN environment variable is used to control whether the return values from the two variants of the $EXECUTE command are shifted down by 8 bits or not.

The $EXECUTE statement has the following format:

$EXECUTE cmd$[,return$],er

Where, return$ is an optional string which receives any output (from "stdout" descriptor) from the command denoted by the cmd$ parameter. By default the value of the status variable, er, may vary dependant on the format used.

The BBEXECRETURN environment variable is a bit-mask with the following values:

1 | The er value from the $EXECUTE cmd$[,return$],er version of the command will NOT be shifted down by 8 bits.
2 | The er value from the $EXECUTE cmd$,er version of the command will NOT be shifted down by 8 bits.

By default BBEXECRETURN=0 , resulting in both versions of the command having er values that are shifted down by 8 bits.

This environment variable can be changed by a $PUTENV statement.

Example

BBEXECRETURN=0


BBEXTENSION

Description

The BBEXTENSION environment variable provides support for B32 nuances & SuperDOS Business BASIC extensions. It is set to indicate that certain commands and statements are to behave as they did under B32 Business Basic, or that SUPERDOS Business BASIC's language extensions are to be used.

If BBEXTENSION is set to B32, certain commands and statements behave as they did under B32 Business Basic.

The majority of the SuperDOS Business BASIC statements are supported, and other major extensions may be added in the future. Refer to the section SUPERDOS.

BBEXTENSION can also be set to UBB if you wish to implement nuances of the language without invoking full B32/SuperDOS emulation. Use of these extensions results in program SAVE files being INCOMPATIBLE with all revisions prior to UBB v3.00.

This environment variable cannot be changed by a $PUTENV statement.

If an attempt is made to use an invalid setting for BBEXTENSION, U/BL displays the following warning message when it is invoked (U/BL starts up as normal after displaying the message):

WARNING: BBEXTENSION invalid (<invalid setting>)

Besides directly affecting the operation of the statements subject to the nuances of B32 and SuperDOS, BBEXTENSION influences the default setting of the BBJULIANFLAGS environment variable. This is so that the operation of the Julian date routines mirrors the target version of Business BASIC. However, should BBJULIANFLAGS be explicitly set, BBEXTENSION will not select the particular Julian date functionality of the flavor of BBASIC U/BL is emulating as BBJULIANFLAGS takes priority over BBEXTENSION. For full details of the BBJULIANFLAGS environment variable refer to its separate documentation entry.

Example

The BBEXTENSION environment variable is set as follows:

BBEXTENSION=B32 | : or
BBEXTENSION=SDOS | : or
BBEXTENSION=UBB | : or if both
BBEXTENSION=UBB,B32 | : or
BBEXTENSION=UBB,SDOS |


BBEXTN

Description

The BBEXTN environment variable defines SAVE program files extensions.

The IMPORT facility allows a defined extension to be added to the resultant SAVE files. This is achieved by setting the environment variable BBEXTN to the required extension. The extension can optionally include the 'full stop', for example, '.ext' or 'ext.'. IMPORT then removes the right most extension from the source file and replaces it with the BBEXTN value as the SAVE file. If the right most source file extension is the same as the BBEXTN value then that source file is NOT processed, to avoid overwriting the source.

If the BBEXTENSION environment variable is set to include B32, U/BL will add BBEXTN's setting to program names which already contain '.' extensions.

U/BL will add the extension to program names which don't have one already. This is especially useful for programs which have been imported from B32, for example, where programs may be referenced in CHAIN or SWAP statements without their program name extensions.

This environment variable cannot be changed by a $PUTENV statement.

Example

Source File prog.ex1.ex2 (MS-DOS only allows ONE extension)

BBEXTN=.sv or BBEXTN=sv

SAVE File prog.ex1.sv

LOAD "TEST" will look for TEST.SV and then TEST

LOAD "TEST.PR" looks for TEST.PR only

CHAIN "=TEST" will look for TEST in the current directory

SWAP "!/path/TEST" looks for /path/TEST

SAVE "TEST" will create TEST.SV

REPLACE "TEST.PR" will REPLACE TEST.PR


BBEXTRAJOBS

Description

The BBEXTRAJOBS environment variable can be used to create additional job slots above the licensed user number (LUN). Setting this environment variable will allow you to set up a BBTTYS file to contain as many workstations as are on the network.

BBEXTRAJOBS provides a solution for sites where there are more users than job slots and a BBTTYS file is in use. Note, however, that the maximum number of simultaneous users is still controlled by the LUN.

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBEXTRAJOBS=3

If the Transoft Licence banner allows two users, setting BBEXTRAJOBS to three will create five slots in the job table. This means that a BBTTYS file can then be set up to include five entries. Only two users will be allowed to use the product simultaneously.

See also

BBNJOBS


BBFCB

Description

The BBFCB environment variable specifies certain FCB (file control block) information that under SuperDOS Business BASIC is normally contained as part of the file. Some of the FCB information is held in record zero of each file, but not the directory structure of "drive/unit #" and "user_group".

BBFCB=drive:user_group, for example, BBFCB=5:12. Note the use of the colon ':' separator.

When executing X$=FCB$(chan), this environment variable will store in X$ at the correct offset the "drive" and "user_group" information.

This environment variable may be extended in future to support other FCB information.

Note: The environment variable BBEXTENSION must also be set to include SDOS.

This environment variable can be changed by a $PUTENV statement.

If an attempt is made to use an invalid setting for BBFCB, U/BL will display the following warning message when it is invoked (U/BL will start up as normal after displaying the message):

WARNING: BBFCB invalid (<invalid setting>)

Example

BBFCB=5:12

See also

BBEXTENSION


BBFFONPPCLEAR

Description

Setting the BBFFONPPCLEAR environment variable to Y makes U/BL send a form-feed character to the screen instead of "ed" (erase display) from the TDF when in print pass through mode.

Example

BBFFONPPCLEAR=Y


BBFLUSH

Description

If the BBFLUSH environment variable is set to Y, the screen print buffer will be flushed every time a new-line is printed.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBFLUSH=Y


BBFREEZE

Description

The BBFREEZE environment variable defines the maximum number of concurrent CHFREEZE statements.

The number of concurrent CHFREEZE statements is limited by the amount of available memory. If a lot of CHFREEZE statements are active at any one time this can cause problems as the available memory gets used up.

BBFREEZE can be set to the maximum number of CHFREEZE statements, which are to be allowed at any one time. The environment variable's setting is used to calculate the amount of memory which is to be allocated for use by CHFREEZE statements.

The amount of memory allocated is calculated as follows:

(BBFREEZE * BBCHAN * 8) bytes

If an attempt is made to exceed this amount, U/BL will generate an error:

9198 - Too many active CHFREEZEs.

If this environment variable's setting is changed, then the change must be made before U/BL is invoked.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBFREEZE=10

See also

CHFREEZE


BBFVAL

Description

If the BBFVAL environment variable is set to N, F_VAL statements are LISTed as VAL statements. By default, variables defined by $NUMERIC are converted to F_VAL if used in VAL statements. For example, entering:

00010 REM $NUMERIC NUM(4.2)

00020 LET NUM=VAL(X$,DUMMY)

with BBFVAL NOT set would result in line 20 being LISTed as:

00020 LET NUM=F_VAL(X$,DUMMY)

whereas setting BBFVAL=N would result in line 20 being LISTed as:

00020 LET NUM=VAL(X$,DUMMY)

This environment variable cannot be changed by a $PUTENV statement.

Example

BBFVAL=N

See also

$NUMERIC

VAL


BBGENTAPE

Description

The BBGENTAPE environment variable is related to the MTDIO statement. If your system does not support a specific tape driver, you may use the generic device handler, which allows MTDIO to offer limited support of a tape device. To enable the generic device handler, set BBGENTAPE to Y in your environment.

Refer to the entry for MTDIO for a full description of its use of the generic tape driver.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBGENTAPE=Y

See also

MTDIO


BBGETCMD

Description

The BBGETCMD environment variable makes the SWAP "xxx/yyy" statement treat the "yyy" as an argument.

Under SuperDOS Business BASIC (and U/BL's emulation thereof) SWAPping to "prog/xyz" will pass control to the program 'prog' and treat 'xyz' as an argument for the program to be accessed by the GETCMD command.

Normally under U/BL outside of SuperDOS emulation, this form of SWAP will be regarded as an attempt to run the program 'prog/xyz', that is, the program 'xyz' in a directory called 'prog' under BBPROGS or BBSEARCH. By setting BBGETCMD=Y, the operation of U/BL can now be modified so that 'prog/xyz' is treated as program 'prog' and argument 'xyz', regardless of the setting of BBEXTENSION.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBGETCMD=Y


BBGLOBLOCK

Description

The BBGLOBLOCK environment variable defines the full path name of a text file which contains a list of all of the global locks which can be applied by the application.

When U/BL is invoked, this file will be read into memory for optimum performance. When a lock request is made to U/BL's lock handler, this table will be searched. If an exact match is found, then the current value of the environment variable BBPREFIX is not added to the file name. If the file specified by BBGLOBLOCK cannot be accessed or read, or if there isn't enough memory available to hold the table, then U/BL will generate the error:

9453 - Cannot access or create memory for global locks file (BBGLOBLOCK).

Since there will be extra processing involved when BBGLOBLOCK is set, there may be a marginal degradation in lock performance, especially if the number of entries in this file becomes very large. However, this solution requires no programming changes to the application.

If BBGLOBLOCK is set, then changes to the environment variable BBPREFIX via a $PUTENV statement will not have any affect.

Any entry in the file which has a '#' or a ':' as its first character will be treated as a comment, and will therefore be ignored. This environment variable cannot be changed by a $PUTENV statement.

Example

BBGLOBLOCK=/u/ubl/GLOBLOCKS

where entries in /u/ubl/GLOBLOCKS would look like:

: List of global locks. Set BBGLOBLOCK to the full path

: name of this file

MASTER

MASTIX

CUSTIX

See also

BBPREFIX


BBGROUP

Description

The PRINT USING formats have been extended for grouping the 'G' format.

When executed, any 'G' format is substituted by the value of the environment variable BBGROUP, which can be dynamically changed in a program via the $PUTENV statement.

This facility allows the reduction in the length of PRINT USING formats by allowing the 'G' to represent any complex set of format characters. The only restriction on its use is that repeat counts cannot be specified in the BBGROUP environment variable.

Example

$PUTENV "BBGROUP","' , ',T0,D10.2' '"

PRINT USING "'Output = 'G2G",1234567,7654321,987789

will give: Output = 12,345.67 76,543.21 9,877,89

and:

$PUTENV "BBGROUP","'Text = ',A6"

PRINT USING "'Numerics = ',E3.0,E3.0,G",12,34,"qwerty"

will give: Numerics = 12 34 Text = qwerty

but:

$PUTENV "BBGROUP","2(' , ',T0,D10.2)"

is illegal as it includes a repeat count. However this can be written:

$PUTENV "BBGROUP","' , ',T0,D10.2, ' , ',T0,D10.2"

or:

$PUTENV "BBGROUP","' , ',T0,D10.2"

and using '2G' in the format string.


BBGUICURSORUPDATE

Description

Setting the BBGUICURSORUPDATE environment variable to Y, causes U/Gi to restore the cursor position from U/Gi after a WSHOW or WHIDE statement. This can cure problems with the display when swapping between windows without an intervening PRINT@(r,c) statement, but will slow the display down.

Example

BBGUICURSORUPDATE=Y


BBGUIMAP

Description

Text strings can be passed between U/BL and the Windows Objects supported by U/Gi to be translated according to the TDF, in either direction. The direction is described as:

Outgoing | When strings are being passed from U/BL to U/Gi
Incoming | When strings are being passed from U/Gi to U/BL.

The translation can be turned on or off independently in each direction. The default settings are controlled by the BBGUIMAP environment variable. This is a two-character string. The first character controls 'Outgoing' translation and the second controls 'Incoming' translation; if the character is 1 then the translation is turned on, otherwise it is turned off.

If the BBGUIMAP environment variable is not set, then the "default default" settings turn both translations off. The BBGUIMAP (or "default default", if BBGUIMAP is absent) settings are applied when the program starts and reapplied whenever the WINIT statement is called.

Example

BBGUIMAP=11 - Turns on translation in both directions

BBGUIMAP=01 - Turns on Incoming (U/Gi to UBL) translation only.


BBGUITIMEOUT

Description

The BBGUITIMEOUT environment variable can be set to a timeout value (in seconds) which represents the time U/Gi will wait before it times out.

A DDE operation in U/BL may take a significant amount of time. If U/BL times out before the end of the operation, the value of the BBGUITIMEOUT environment variable can be increased.

The default setting for this environment variable is 5 (seconds).

Example

BBGUITIMEOUT=10


BBGUIUSERMODE

Description

Setting the BBGUIUSERMODE environment variable to Y, prevents the return of the error code on commands that don't require a status return, and thus speeds up access. Use with the GETGUIOPT(4) statement, which returns the number of errors returned since the last call to GETGUIOPT(4). The default setting for this environment variable is N.

Note: Do not use during development process as programming errors will be missed.

Example

BBGUIUSERMODE=Y


BBGUIXTOFILETRANSFER

Description

Setting the BBGUIXTOFILETRANSFER environment variable to Y, maps old _GUIX (70/71/90/91) file transfer commands onto the FILETRANSFER command. This gives a faster, silent transfer (without a dialog box), with no reliance on the 'sz' or 'rz' utilities.

Note: This environment variable applies to UNIX only. This behavior is automatic under Windows.

Example

BBGUIXTOFILETRANSFER=Y


BBHANGUP

Description

If your hardware supports the generation of SIGHUP, then setting the BBHANGUP environment variable to Y will ensure that U/BL sessions running on terminals that have been switched off will be closed down cleanly.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBHANGUP=Y


BBHBUILD

Description

If the environment variable BBHBUILD is set to "Y", then each time the HELP key is used, the user is asked to provide a field length and menu item name. This information, together with the current screen coordinates, is appended to the end of the file identified by the BBHELP environment variable.

In this way, context sensitive Help messages can be created easily. Once all the context sensitive Help details have been entered, BBHBUILD should be switched off, that is, set to "N" or removed from the BBENV file.

This environment variable can be changed by a $PUTENV statement.

Example

BBHBUILD=Y


BBHELP

Description

The BBHELP environment variable defines the help text file.

During processing the current help file can be changed by the use of the $PUTENV statement.

If an invalid directory or file is used in setting BBHELP, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBHELP contains invalid directory/file <pathname>

Example

Under Windows

BBHELP=\USER\DATA\HELPFIL

Under UNIX

BBHELP=/user/data/HELPFILE


BBHIGHKEY

Description

By default, U/BL returns high values if a key cannot be found using the KFIND statement. By setting the BBHIGHKEY environment variable to Y, U/BL will return the highest user key in the index instead. The record number will still be zero.

This environment variable is intended mainly for use with BBEXTENSION set to include SDOS, since this was the default action of the SuperDOS interpreter.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBHIGHKEY=Y


BBHITEM

Description

Normally, when the Help Hot Key is hit in any program the Help facility searches the Help text file, defined by the BBHELP environment variable, for the entry:

. progname

When found the text following is selected.

However, if the BBHITEM environment variable is set to any name, for example, genledger, then the Help facility searches the Help text file for both the program name and the BBHITEM name. Whichever is found first will denote the text displayed as the help.

This environment variable only works on program name lines, that is, the '.' lines in the help text file. The program name does not have to be a real program.

This is useful for providing 'global' help across a number of programs. For example, you may have an entry in your Help text file called .accounts. By setting BBHITEM=accounts at particular points in your application, you can get general help on the topic of accounts as opposed to help for a specific program.

This environment variable can be changed by a $PUTENV statement.

Example

BBHITEM=genledger


BBHMEM

Description

By default a maximum of 1100 characters under Windows and 2600 characters under UNIX may appear in the Help-Index Menu (this is the total '!items' lines for the particular program). To increase this value set the BBHMEM environment variable to the number of characters you require.

The number of characters allowed in the Help-Index Menu includes an allowance for the control structures for each item. The numbers are calculated as follows:

UNIX - Number of characters + 16 * Maximum no of topics

Windows - Number of characters + 12 * Maximum no of topics

The default number of items on an Help-Index Menu is 100, but this can be increased by setting the environment variable BBTOPICS.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBHMEM=1000

See also

BBHTEXT

BBTOPICS


BBHOME

Description

The BBHOME environment variable specifies a sub-BBROOT directory that will be automatically changed to when the product is invoked. For example:

BBROOT=/usr

BBHOME=/usr/mydir

will change directory to /usr/mydir on start up. If you want to start in your current working directory, set BBHOME to '.' (BBHOME=.).

If the directory specified by BBHOME cannot be accessed, either because it is not below the BBROOT directory, or it doesn't exist, or you don't have access permissions to it, an error 9402 will be generated when you try to invoke U/BL and you will not be allowed to continue.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBHOME=/u/user/data

See also

BBROOT


BBHTEXT

Description

The BBHTEXT environment variable defines the number of characters allowed in the Help text. The default is 10240 characters.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBHTEXT=12000

See also

BBHMEM

BBTOPICS


BBICHR

Description

If the BBICHR environment variable is set to BBICHR=CR, then carriage returns will be ignored when using the INPUT FILE USING statement.

If the BBICHR environment variable is set to BBICHR=NL, then new lines will be ignored when using the INPUT FILE USING statement.

This is needed because the MS-DOS line terminator (<CR><NL>) would otherwise cause incorrect unpending on the INPUT FILE USINGs. If BBICHR is not set, then no characters will be ignored.

This environment variable can be changed by a $PUTENV statement.

Examples

BBICHR=CR

BBICHR=NL


BBIKEYWAIT

Description

If the BBMIKEY environment variable is set to "Y", and an ESC character is detected in the input stream, the product waits a tenth of a second for any following characters which together with the ESC may form a special sequence, for example, a function key or an arrow key.

The BBIKEYWAIT environment variable allows you to increase, or turn off, the waiting time. Typically, it will be used when running over a TCP telnet, where the tenth of a second delay is often not long enough.

This environment variable cannot be changed by a $PUTENV statement.

Examples

BBIKEYWAIT=3 : a wait period of .30 of a second

BBIKEYWAIT=0 : disable the delay - useful if using

: the <REPT> (repeat) key

See also

BBMIKEY


BBINIT

Description

The BBINIT environment variable requires variables to be declared/assigned before use. Normally, variables are not required to be declared or assigned before use. Thus the default is N.

If you wish to trap uninitiate variables at run time, this environment variable must be set when the program's source code is ENTERed, and when the program is RUN.

If the code has been ENTERed with BBINIT=Y, you can enable (BBINIT=Y) or disable (BBINIT=N) the checking for initialization of variables when RUNning the program. If BBINIT=N, or if it isn't set, at ENTER time, BBINIT has no effect at RUN time, and no uninitiate variable checking will be carried out.

ENTERing a program's source code with BBINIT set to N results in smaller SAVE files, and will marginally improve the program's RUN time performance. However, programs ENTERed this way will NOT generate any uninitiate variable errors.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBINIT=Y


BBIPTTY

Description

The BBIPTTY environment variable allows U/BL when used in conjunction with U/Gi running in GUI mode over a TCP/IP connection, to specify SYS(4) values based on the machine the U/Gi client is running on.

This is achieved by specifying a mapping, via the BBTTYS file between the client PCs hostname and the SYS(4) value(s) to be used. Up to 5 separate settings per client PC are allowed. The SYS(4) values are specified as a comma separated list of numbers following the hostname of the particular client PC. For example:

client1 | 1, 21, 41, 61, 71
client2 | 2, 22, 42, 62
client3 | 3, 23

By default the BBIPTTY environment variable is set to Y.

To disable the functionality where the BBTTYS lookup uses the client PC's hostname (local username if from a terminal server machine), set the BBIPTTY environment variable to N. This replicates the functionality of running U/BL in non-GUI mode. Under these circumstances, the BBTTYS lookup uses the name of the pseudo-tty on which U/BL is running.

Example

BBIPTTY=N


BBJULIANFLAGS

Description

This environment variable allows explicit control over how U/BL's Julian date routines work. As U/BL is an emulator, its default operation must follow the flavor of Business BASIC that is being emulated. From a point of view of making an application year 2000 compliant, the functionality this results in may not be that which is easily adapted to full compliance. This switch is provided so that the operation of the Julian-based statements can be selected so as to minimize any year 2000 compliancy work that is needed in the BBASIC application.

BBJULIANFLAGS is implemented as a bit mask, the value of the environment variable's setting determining what Julian date functionality U/BL offers. The following table outlines the individual flags implemented in the bit mask:

Bit

Value

Controls

0

1

Range validation for day, month and year values.

If this bit is set, all Julian date routines check that the supplied date is valid. For instance, April 31st or month 13 will be regarded as illegal and be rejected by the Julian routines. This setting directly replicates the way in which SuperDOS Business BASIC operates. Unset, range validation is not performed.

1

2

Months >12 imply the 1st month of the following year.

If set, this switch causes any month greater than 12 to be regarded as the first month of the following year. This setting directly replicates the way in which Data General Business BASIC operates.

2

4

Months >12 are treated as offsets into future years.

Setting this switch causes any month greater than 12 to be regarded as an offset into the following years. For example, the 1st of the 13th month is regarded as the 1st of the 1st month of the following year, the 1st of the 14th month is regarded as the 1st of the 2nd month and the 1st of the 25th month is regarded as the 1st of the 1st month two years later. This setting directly replicates the way in which Data General Business BASIC operates.

3

8

All centuries are regarded as leap years.

This switch causes the Julian date routines to operate in a non year 2000 compliant manner in that the leap year calculation will regard all century dates (the year CC00) as leap years. In reality, only those century dates divisible by 400 should be regarded as a leap year. This switch is provided to allow U/BL to emulate the functionality exhibited by Data General's Business BASIC in case any applications rely on this behavior. While this operation is not strictly year 2000 compliant, it may not prevent correct operation of any system until well into the next century (if dates far forward of the current date are not processed) or at all (if the application takes account of this behavior). Unset, this switch correctly calculates whether any year is a leap year.

4

16

Invokes date windowing support.

This switch makes all of the Julian date routines expect or produce date-windowed years. Date windowing is fully explained in the documentation for BBDATEWINDOW an environment variable which, if set, implicitly sets this switch. The use of date windowing functionality emulates the way in which SuperDOS Business BASIC worked (assuming that BBDATEWINDOW=1968), it is also the way in which U/BL operated when BBSDOSDATE was set. If this switch is not set, all dates are regarded or returned either as a full 4 digit year or as an offset from 1900 (dependant on the settings of bits 13 and 14).

5

32

Produce a 2 byte Julian value.

Setting this bit ensures that any Julian date generated is a 2 byte quantity. Julian values greater than 65535 wrap back to 0. For example, using this switch under full DG emulation we get:

STMA 12,J,6,4,247 : returns 65535

STMA 12,J,6,5,247 : returns 0

STMA 12,J,6,6,247 : returns 1

This functionality replicates that exhibited by both Data General Business BASIC and B32.

6

64

Use only the low 2 bytes of the Julian value.

This bit controls whether only the low 2 bytes of any Julian value are interpreted to determine the date represented. This functionality emulates the way in which B32 operated.

7

128

Return a Julian value of 57418 for 0/0/0.

Setting this switch causes the null date, 0/0/0 to return a Julian value of 57418 as B32 would have done. If neither this or bit 8 are set, the null date returns a Julian value of 0.

8

256

Return a Julian value of 57449 for 0/0/0.

Similar to bit 7, setting this switch causes the Julian date routines to behave as Data General Business BASIC and return a value of 57449 when processing the null date.

9

512

Regard the 0 Julian value as 0/0/68.

The Julian date 0 is usually regarded as representing the 0th day of the 1st month 1968. If this switch is used, such a date is returned as the 0th day of the 0th month as under SuperDOS Business BASIC.

10

1024

Offset Julian values by 16384 (B32 operation).

Using this switch selects the B32 functionality of adding 16384 to dates prior to 1/1 1968. This includes offsetting dates such as 1/0 1968 or 1/-1 1968 and it is in this respect that this switch differs from bit 11. If neither this switch or that selected by bit 11 are employed, dates prior to 1/1 1968 return negative Julian values (31st Dec 1967 returns -1; while the 30th returns -2)

11

2048

Offset Julian values by 16384 (DG operation).

Using this switch selects the Data General functionality of adding 16384 to dates prior to 1968. Unlike the similar B32 functionality dates such as 1/0 1968 or 1/-1 1968 are not offset. Once again, If neither this switch nor by bit 10 are set, dates prior to 1/1 1968 return negative Julian values (31st Dec 1967 returns -1 and the 30th returns -2)

12

4096

Generate a run-time error for illegal date conversions.

Using this switch causes any attempt to convert an illegal date to generate a run-time error 9874. An illegal date is one where:

  • The date cannot exist, for example, 30th Feb 2000

  • The date falls outside of any date window that is in use, for example, if a Julian converts to 1st Jan 2068 and the windowed range is 1968-2067

  • If range checking is enabled (bit 1 is set) and the month or day is out of the valid range

If this switch is not selected, all invalid conversions will return a null date (a Julian date of 0 or the date 0/0/0)

13

8192

Regard 4 digit years as CCYY.

If this bit is set, any 4 digit year (>999) supplied to a Julian date routine is interpreted to be in the form CCYY and will not be treated as an offset from 1900 or as a windowed date (as dictated by bit 4).

Note: Bits 5 and 6 restrict the Julian value to 2 bytes and therefore cause problems with correct signing of the result when converting a date prior to the base date to a Julian value. If you wish to use dates prior to the base date bits 5 and 6 must not be set in your value for BBJULIANFLAGS.

14

16384

Return 4 digit years.

Setting this switch causes all conversions from a Julian date to return the year in the 4 digit form CCYY, rather than the more usual offset from 1900 or windowed date (as selected by bit 4).

Note: Bits 5 and 6 restrict the Julian value to 2 bytes and therefore cause problems with correct signing of the result when converting a date prior to the base date to a Julian value. If you want to use dates prior to the base date, bits 5 and 6 must not be set in your value for BBJULIANFLAGS.

15

Reserved.

16

Reserved.

17

131072

When the U/BL Julian date routines are configured to return negative values for dates prior to the base date a Julian value of zero is not usually regarded as any specific date. Dependent on bit 9 of BBJULIANFLAGS it is regarded as either 0/0/68 or 0/1/68. This can prevent arithmetic being performed on the Julian values when two dates lie either side of the base date. Consider the following example:

Date | Julian Date
29/12/67 | -3
30/12/67 | -2
31/12/67 | -1
01/01/68 | 1
02/01/68 | 2
03/01/68 | 3

Days between 01/01/68 and 03/01/68 = JD(03/01/68) - JD(01/01/68)

= 3 - 1 = 2 CORRECT

Days between 31/12/67 and 03/01/68 = JD(03/01/68) - JD(31/12/67)

= 3 - -1 = 4 WRONG

However, setting the flag bit 17(131072) regards the Julian value of zero as the day before the base date, that is:

Date | Julian Date
31/12/67 | 0
30/12/67 | -1
29/12/67 | -2

This setting is useful when dates prior to the base date are allowed (that is, bits 10 and 11 are not set). This enables improved date arithmetic with dates either side of the base date.

The disadvantage of this switch is that unless invalid Julian conversions are set so to generate an error (bit 12 of BBJULIANFLAGS), it is hard to tell if the zero return from a date to Julian conversion represents the day before the base date or an error.

18+

Reserved.

To set BBJULIANFLAGS, simply add together the value of all the individual switches that you wish to use. For instance:

Functionality Required | Value
Range validation for day, month and year values | 1
Regard the 0 Julian value as 0/0 1968 | 512
Generate a run-time error for illegal date conversions | 4096
Regard 4 digit years as CCYY | 8192
Return 4 digit years | 16384
+ | --------
Value for BBJULIANFLAGS | 29185

Using the above example value for BBJULIANFLAGS will cause any Julian date conversion to accept or return 4 digit years, erroring if the supplied information is outside of the expected values (for instance if the value for the day being converted is greater than the number of days in the particular month being converted). As neither switch for adding 16384 to the Julian value associated with date prior to 1968 ('B32 functionality' set by value 1024 or 'DG functionality', value 2048) has been selected, all dates prior to 1968 return a negative Julian value.

When calculating BBJULIANFLAGS, bear in mind that not all of the settings can be used together. This is because many of them contradict each other. For instance, there is little point in setting flags '1' and '2' together as these tell U/BL to do two contradictory things (regard the 13th month as illegal but also accept it as the first month of the following year). As BBJULIANFLAGS controls the date interpretation of the Julian date routines, it has a very large effect on the functionality of the following BBASIC statements:

_CHECK | FCB | FCB$ | FROMJULIAN
STMA 11 | STMA 12 | STME 6 | STME 7
SYS(152) | TOJULIAN | @INPUT | @PRINT
$DATE$ | $VDATE |  |

Any Julian date produced using one of these statements under one setting of BBJULIANFLAGS, may be interpreted differently if converted back using another setting of the variable. For this reason, despite the fact that BBJULIANFLAGS is $PUTENVable, Transoft strongly suggest that you standardize on a fixed setting for BBJULIANFLAGS. Should mixed values of BBJULIANFLAGS be used against the same data, it is quite possible that data corruption may occur. For instance, if one program is designed to use the functionality of Data General's Business BASIC where the year 2100 is regarded as a leap year, and another is designed to expect the correct results where 2100 is not a leap year, if one program looks at the data produced by the other program (with a differing value of BBJULIANFLAGS), dates past 28th Feb 2100 will have a Julian value which differs by one, so while one program would regard the Julian value of 48274 as 2nd March 2100, the other would treat this as March 1st.

By explicitly setting BBJULIANFLAGS, the user may select the way in which U/BL's Julian date routines interpret dates. This is so the functionality that best suits making the BBASIC application year 2000 compliant may be selected. Unset, BBJULIANFLAGS defaults so that the functionality of U/BL emulates that of the BBASIC U/BL is modeling at the time (as selected by the BBEXTENSION environment variable). This results in the following default settings for BBJULIANFLAGS:

If BBEXTENSION is not set (or set to UBL) - Data General Emulation.

Functionality Required | Value
Assume months >12 infer the 1st month of the following year | 2
Regard all century years as a leap year | 8
Produce a 2 byte Julian date value | 32
Return a Julian value of 57449 for the date 0/0/0 | 256
Offset Julian values by 16384 (using DG functionality) | 2048
+ | --------
Value for BBJULIANFLAGS | 2346

If BBEXTENSION is set to B32 - B32 Emulation.

Functionality Required | Value
Assume months >12 are offset into the following years | 4
Produce a 2 byte Julian date value | 32
Use only the low 2 bytes of a Julian date value | 64
Return a Julian value of 57418 for the date 0/0/0 | 128
Offset Julian values by 16384 (using B32 functionality) | 1024
+ | --------
Value for BBJULIANFLAGS | 1252

If BBEXTENSION is set to SDOS (or if BBSDOSDATE=Y) - SuperDOS Emulation

Functionality Required | Value
Range validation for day, month and year values | 1
Support date windowing | 16
Regard the 0 Julian value as 0/0 1968 | 512
+ | --------
Value for BBJULIANFLAGS | 529

Allowing BBJULIANFLAGS to default (or explicitly setting it to the default value for the emulation mode in operation) decides both the general functionality of the date handling (how years are interpreted) and selects the nuances of that particular BBASIC. While the individual nuances only have real relevance to software which either expects this somewhat quirky functionality or has coded around the limitations, the general methods for year interpretation are worth detailed consideration.

With U/BL 2.10, there are basically three methods of specifying a year to the Julian date routines. These are as follows:

  • As an absolute, 4 digit year - CCYY

  • As an offset from the year 1900, in either 2 or 3 digits (101 implies the year 2001)

  • As a windowed date, any 2 digits represents a year within 100 years of the window's base

The value of the BBJULIANFLAGS environment variable determines which method is in use at any one time. Whichever method is in use allows the Julian date routines to uniquely determine what year the user is attempting to convert. In fact, the year inferencing is not solely confined to the Julian date routines. The year inferencing selected by BBJULIANFLAGS is also used by the $VDATE statement when using a date string which doesn't have a 4 digit date (edit formats 1-8).

The 4 digit year functionality selectable by BBJULIANFLAGS is a new addition to the product. Previously (or when BBJULIANFLAGS does not enable this functionality), 4 digit years were either regarded as being illegal (under date windowing, SuperDOS emulation) or treated as a 4 digit offset from 1900. This meant, the dates were either rejected or had their leap year calculations based on 1900+YYYY rather than treating the year as absolute. Apart from the individual control the user now has over the date processing routines, the other main functionality advance with U/BL 2.10 is the ability for the Julian date routines to generate a run-time error if a conversion is attempted which uses incorrect data. This feature is of significant benefit when converting applications to be year 2000 compliant as illegal date values, outside of the pattern being supported by the application, is effortlessly trapped during run-time.

Example

BBJULIANFLAGS=529

This ensures that all of U/BL's Julian date routines will:

  • Use date windowing to infer the date's century;

  • Range check for illegal days of the month or months of the year;

  • Return a date of 0/0/68 for a zero Julian date.


BBKCHAN

Description

The BBKCHAN environment variable allows the direct use of the physical channel number in K-statements.

Normally K-statements (KADD, KFIND) can take a descriptor string or a logical file number. When the environment variable BBKCHAN is set, the logical file number may be replaced by a direct channel number.

Although this is similar to SuperDOS Business BASIC style access, it should be noted that the underlying file structures are in Data General Business BASIC ISAM format,that is, there is no SuperDOS FCB record expected at the start of the file.

This environment variable can be changed by a $PUTENV statement. It has no effect when the BBEXTENSION environment variable is set to SDOS.

Example

BBKCHAN=Y

See also

KADD

KDEL

KFIND

KNEXT

KPREV


BBKEEPSYS4

Description

If the BBKEEPSYS4 environment variable is set to Y, background jobs will not have a SYS(4) value of -1, but will use the next available foreground job slot number instead.

This allows the user to perform background tasks where the application needs a valid SYS(4) value.

Note: The background jobs will use the next available FOREGROUND job numbers, and that this environment variable must be set up as an operating system environment variable, for example, BBKEEPSYS4=Y; export BBKEEPSYS4, and not in a BBENV file. It must be set before Basic is invoked.

Example

BBKEEPSYS4=Y

See also

BBDUPSYS4

BBSYS4INC


BBKEY

Description

The BBKEY environment variable allows a developer's software to be made non-LISTable by any other user, even with BBDEBUG=Y set. This security is achieved by setting BBKEY up to a 20 character code.

Every program SAVEd or REPLACEd, when BBKEY is set, will have the 'code' encrypted into it. Programs which include the 'code' may only be reLISTed if BBKEY is set to the same 'code' as the original. Programs that do not have the encrypted 'code' may be run with those that do.

If BBKEY is not set, then in order to LIST a program without the 'code' after trying to LIST a program that did have the 'code', then a NEW must be entered to clear the BBKEY buffer. IMPORTing with BBKEY set will include the security 'code' in each program.

This environment variable can be changed by a $PUTENV statement.

Example

BBKEY=this_is_my_code

See also

BBDEBUG


BBKEYDEV

Description

The BBKEYDEV environment variable defines which port the security key is attached to, namely com1, com2, lpt. The product will then interrogate that particular port, rather than search in turn from com1.

If an attempt is made to use an invalid setting for BBKEYDEV, U/BL will display the following warning message when it is invoked (U/BL will start up as normal after displaying the message):

WARNING: BBKEYDEV invalid (<invalid setting>)

This environment variable cannot be changed by a $PUTENV statement.

Examples

BBKEYDEV=com1

BBKEYDEV=com2

BBKEYDEV=lpt


BBLARGEFILES

Description

The BBLARGEFILES environment variable must be set to Y if you want to use files larger than 2GB in size (U/BL Large FIle Support).

This must be set in the environment when the U/BL runtime is started as well as when U/BL is started. The default value for BBLARGEFILES is N. It cannot be set dynamically using the $PUTENV statement.

If BBLARGEFILES is set to Y, then the BBPRECISION environment variable must be set to 8 when U/BL is started to enable the use of 8 byte numeric values. If BBLARGEFILES is set to Y then it will not be possible to change the setting of BBPRECISION dynamically during a U/BL session using the $PUTENV statement.

Example

BBLARGEFILES=Y


BBLASTKEY

Description

If the BBLASTKEY environment variable is set to Y, then duplicate keys will be added to the end of the duplicate key list, that is, first in, first out. If BBLASTKEY is not set, or if it is set to N, then duplicate keys will be added to the beginning of the duplicate key list, that is, last in, first out.

This environment variable has been added to emulate the way that SuperDOS Business BASIC handles duplicate keys, but note that the BBEXTENSION environment variable does not have to be set to include SDOS if you wish to use BBLASTKEY.

It will be necessary to recreate any indexes that are to use this mechanism in order to maintain a consistent index structure. Failure to do so may result in corruption.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBLASTKEY=Y


BBLFTABOVR

Description

Setting the BBLFTABOVR environment variable to Y stops the LOPEN statement from checking that the corresponding logical file number in the LFTABL$ is in use (not null filled) before allowing the open to take place. Normally, if the record in LFTABL$ is occupied, the LOPEN statement generates an error regardless of whether the record was in use by a logical file or not.

Example

BBLFTABOVR=Y


BBLIB

Description

The BBLIB environment variable defines program libraries. Program libraries are files containing many program SAVE file images, with a hashed index to them. The libraries are kept open, so saving overhead when programs are CHAINed or SWAPped to. Under Windows, two libraries may be kept open while on all other operating systems, up to ten libraries are supported concurrently.

The STMA 20 statement is supported, but its use is not mandatory as the presence of the environment variable BBLIB implies using program libraries. The library based program names, which are CHAINed or SWAPped to, are not required to begin with a "%" character.

A utility, written in C and called PLB (Program Library Builder), is provided to create the libraries.

If an invalid directory or file is used in setting BBLIB, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBLIB contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Examples

Under Windows

BBLIB=\USER\PROGS\.;\USER\LIB\SALESLIB

Under UNIX/Xenix

BBLIB=/user/test/.:/user/lib1/saleslib

The libraries are searched in order for the required program, and the "." implies that in that directory the programs are not in a library and will be searched for directly by the operating system. If a program is not found in the BBLIB path, then the BBPROGS and/or BBSEARCH paths are searched. BBLIB takes precedence.

See also

BBPROGS

BBSEARCH

BBSEARCH01-20


BBLIMITNROW

Description

Setting the BBLIMITNROW environment variable to Y (BBLIMITNROW =Y) forces any PRINT @(ROW,COL) commands with a ROW that is greater than the number of rows on the screen to go to the last line of the screen. This was implemented to maintain compatibility with DG terminals.

If this environment variable is not set and you use a PRINT @(ROW,COL) command with a ROW that is greater than the number of rows on the screen, then the results are unpredictable, depending on which terminal you are using.

Example

BBLIMITNROW=Y


BBLINE

Description

The BBLINE environment variable defines the maximum length of screen print, INPUT USING and INPUT FILE lines. A valid value is between 14 and 256 characters. The default is 132.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBLINE=160


BBLINK

Description

The BBLINK environment variable defines the links file. Although UNIX and Xenix support as standard the ability to create links across paths, this facility does not exist under Windows. The product supports the concept of links to data files, across all operating system implementations consistently, by providing a link table file, determined by the environment variable, BBLINK, which by default is called 'BBLINKS'. Any program that under Data General Business BASIC creates data file links (using the STMC 21 statement) will set them up in this link table.

If logical files are being used, then the links file will be used to hold details of the '.VL' names. It is recommended that, where possible, operating system links are used, as this improves performance.

It is recommended that the links file resides in the root of the data directory, that is, the directory defined by the BBROOT environment variable.

If an invalid directory or file is used in setting BBLINK, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBLINK contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBLINK=\USER\DATA\LINKFILE

Under UNIX

BBLINK=/user/data/LINKFILE

See also

BBLINKTYPE

BBRESOLVE


BBLINKS

Description

The BBLINKS environment variable


BBLINKTYPE

Description

The BBLINKTYPE environment variable defines the type of file linking that is to be used. It can be set to one of the following:

BBLINKTYPE=TABLE | The link table, specified by the environment variable BBLINK, is in use.
BBLINKTYPE=PSEUDO | Pseudo (B32 type) links are supported. The resolution file name will be preceded by @LINK:.
BBLINKTYPE=B32 | As pseudo links.
BBLINKTYPE=SYMBOLIC | Symbolic links will be used (if supported by the operating system).

If the BBLINK environment variable has been set, BBLINKTYPE will automatically be set to TABLE. If the BBLINK and BBLINKTYPE environment variables are not set, and symbolic links are supported, then BBLINKTYPE will be set to SYMBOLIC.

The environment variable BBRESOLVE will be set to "Y" if both BBLINK and BBLINKTYPE are not set, or if BBLINKTYPE is set to PSEUDO or SYMBOLIC. BBRESOLVE has to be set to "Y" for PSEUDO links or the link would not be resolved. The link file would be OPENed rather than the resolution file.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBLINKTYPE=PSEUDO

See also

BBLINK

BBRESOLVE


BBLOCKDG

Description

The BBLOCKDG environment variable allows the return from the LOCK statement to be controlled. By default the LOCK statement follows the Data General standard returning -1 for success. However, if the user sets BBLOCKDG=N then 0 is returned for success, observing the SuperDOS standard.

The BBLOCKDG environment variable is $PUTENVable.

Example

By default:

LOCK 1,"FILE",1,1,code

PRINT code

prints "-1"

PUTENV "BBLOCKDG","N"

LOCK 1,"FILE",1,1,code

PRINT code

prints "0"


BBLOCKSERVER

Description

The BBLOCKSERVER environment variable will cause U/BL to use the B32 Business Basic locking system.

Note: The B32 file and lock manager must be available before this environment variable can be used.

Example

BBLOCKSERVER=Y


BBLONGCMD

Description

Setting the BBLONGCMD environment variable to Y allows a 200 char argument list to be passed in the GETCMD buffer via the command line or the SWAP and CHAIN commands. 100 chars are also allowed for the file or path name, giving an effective total command line length of 300 chars.

If the BBLONGCMD environment variable is not set to Y then, 78 chars are passed. If this environment variable is not set and you attempt to specify an argument list, which is greater then 78 characters in length, then it will be truncated to the 78 characters allowed in the GETCMD buffer. In such a case setting the BBLONCMD environment variable allows the command to be passed correctly.

The BBLONGCMD environment variable is not $PUTENVable.

Example

BBLONGCMD=Y


BBLOPEN

Description

The BBLOPEN environment variable determines how the optional "last record number" parameter on an LOPEN statement should react when it encounters a zero or no parameter. The following examples illustrate this:

Example 1:

OPEN FILE[1,5],"PHYSICAL"

LOPEN FILE[2,1],"LOGICAL","D",64

Example 2:

OPEN FILE[1,5],"PHYSICAL"

LOPEN FILE[2,1],"LOGICAL","D",64,0 : The 0 here is the "number of the last record"

Under Data General Business BASIC, ASC(LFTABL$[21,24]) in the first example is 16777215. In the second example it is zero. In both cases U/BL would display ASC(LFTABL$[21,24]) as 16777215. This is a problem which cannot currently be resolved.

The BBLOPEN environment variable has been provided to work around this problem. If it is set to Y, then U/BL will place zero in LFTABL$[21,24]. If it is not set, or if it is set to N, then U/BL will place 16777215 in LFTABL$[21,24] as it always has done.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBLOPEN=Y


BBLWRITETRUN

Description

By default BBASIC produces an error if an attempt is made to perform an LWRITE of more data than the logical record can hold.

Setting the BBLWRITETRUN environment variable to Y causes U/BL not to produce the error if LWRITE tries to write a string with a length greater than the record length of the logical file. Instead the data written is truncated to the record length.

Example

BBLWRITETRUN=Y


BBMACHINE

Description

The BBMACHINE environment variable allows you to specify what machine you are on. This is useful if you are on a network of machines. This environment variable can be assessed via a $GETENV statement. It is also shown on the ublmon Job Table display.

In future this environment variable will have greater use in networked systems.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBMACHINE=AV4000

BBMACHINE=RS6000


BBMAPFILE

Description

U/BL's printer controls support internal data in a portable manner as 7 bit characters, and allow the use of 8 bit printers.

A printer mapping file, defined by the BBMAPFILE environment variable, containing "from-to" character mappings is created containing a number of sections, one for each named printer. The end of each printer's mapping is denoted by the "/" character.

When a printer is opened via an OPEN FILE statement, the printer name, less the "@" or "$", is looked for in the BBMAPFILE. If found then the print mapping for that printer is installed and the appropriate 7 bit to 8 bit maps used.

The individual mappings appear as a pair of hexadecimal digits; the first being the "original" character, and the second the character that should be output instead.

When printing through the terminal, it is also possible to define printer mapping, by stating which printer in the BBMAPFILE is attached to the particular terminal using the BBCONMAP environment variable. For example, BBCONMAP=vt220. Only one set of mappings can be in use at any one time. If a second printer is OPENed before the first is CLOSEd, then no more mappings will be applied to the first printer (even if the second printer is subsequently CLOSEd.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBMAPFILE=PRINTMAP

BBCONMAP=vt220

PRINTMAP contains:

LPT1

  5e,c8

  6f,d7

  /

  vt220

  5b,b9

  5c,d4

  /

The above entries could be for an IBM printer (LPT1) and a VT220 print-pass-through (vt220).

Note: No blank lines or comments are allowed in the BBMAPFILE.

The only valid entries are a printer name, a pair of comma separated hexadecimal numbers, or a definition terminating "/" character. If the BBMAPFILE is illegal, it will be ignored, and no error will be reported by U/BL.

See also

BBCONMAP

BBSPOOL


BBMEMPOOL

Description

The BBMEMPOOL environment variable must be set to the number of bytes of memory that are to be allocated to a particular session of U/BL, for example 500 000. If BBMEMPOOL is not set, then its default size is 512 000 bytes. A small portion of unused memory is left between the various sections to allow for expansion during the running of a program. If a section uses up all the space available then all the sections above will be dynamically reorganized to make room.

When a program SWAPs, the spare memory at the end of the allocation will be used. If BBMEMPOOL is set large enough, then all SWAP levels will be held in memory and U/BL will run quicker than UBB since there will be no disk access. If there is insufficient room in BBMEMPOOL for the new swap level, then the lowest swap level in BBMEMPOOL will be written to disk.

The number of levels on disk can be seen on the SIZE display.

This environment variable can reduce the amount of memory required to run the application under UBB, as some programs may have required a large BBCODE setting and some a large BBSTRINGS setting. A program requiring the large BBCODE might not use much of the BBSTRINGS area and vice versa.

This environment variable cannot be changed by a $PUTENV statement.

See also

SIZE


BBMIKEY

Description

The BBMIKEY environment variable is used to allow keys that are mapped through the terminal definition file (TDF) to generate an IKEY. Under UNIX the IKEY is detected by the operating system before the product has an opportunity to perform the TDF mapping.

With BBMIKEY set to Y, the product suspends the operating system checking on all INPUT or INPUT USING statements. Each input character is then checked to see if an IKEY should be generated. This allows TDF mappings to be performed before the IKEY check.

The default is N.

This environment variable can be changed by a $PUTENV statement.

Example

BBMIKEY=Y

See also

BBIKEYWAIT

INTERRUPT


BBMOUSE

Description

The BBMOUSE environment variable provides mouse support, allowing simple key stroke emulation based on click and position changes recorded in the mouse processing routines. This enhancement only supports text based displays with no mouse pointer. Setting the BBMOUSE environment variable to Y enables mouse support for existing saved binary files. The default value for BBMOUSE is 'N', that is, no mouse support.

For mouse support to operate you will need to ensure that there is a mouse driver installed prior to entering U/BL. This extension allows the user to enable or disable the state of the mouse

In the 'ON' mode keyboard emulation checking is enabled. The mouse movement and clicks are mapped to emulate key strokes based on the current position as compared with the previously read mouse status. Movement is translated into standard arrow keys, and clicking is translated either into the enter or escape key.

Note: Auto repeat is not enabled, so that holding a mouse button down will only return a key stroke the first time it is detected.

This environment variable can be changed by a $PUTENV statement.

Example

BBMOUSE=Y


BBMSGLK

Description

The BBMSGLK environment variable locks the message queue for inter-processor communication using the STME 13 statement, hence synchronizing access to a global message queue.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBMSGLK=Y

See also

STME 13


BBMULTI

Description

The BBMULTI environment variable sets up the multi-tasking facility as follows:

BBMULTI=<multi-task file> <number of tasks>

where:

<multi-task file> | Is a file into which the tasks are swapped when not "current". It must have the full pathname of the file.
<number of tasks> | Have a value of 2 to 9.

This entry should be placed in the BBENV file. For example:

BBMULTI=C:\USER\BASIC\MTASK.BAS 9

BBMULTI=D:\MTASK.BAS 9 : For RAM disk performance

When the product is brought up, and BBMULTI has been set, the following message is displayed on screen line 25:

UBL-MULTI *** TASK 1 ***

If this message not be displayed, then either BBMULTI has not been set up correctly or it failed. One possible reason for failure is that there is not enough disk space available.

Each of up to 9 tasks is invoked by ALT F1 to F9, or ALT F10 which invokes the "next task". In the TDF file, these function keys are set to return decimal values of 221-229 and 220 respectively. They can, of course, be remapped to other keys if you wish.

Note: On networks, each workstation must have its own multi-task file. If a ramdisk is not available, then the multi-task file should be on the PC's own hard disk.

If using diskless PCs as workstations, then the workstations' multi-task files can be set up on the network drive, but each workstation's multi-task file must have a unique name. There will be an increase in network traffic with a resultant reduction in overall system performance.

Each task is a separate session. It is possible to invoke U/BL with a small driver program that will CHAIN to another program dependent on the new SYS(104) value, which is the task number. For example, the driver program might contain:

00100 IF SYS(104)=1 THEN CHAIN "PROGMENU"

00110 IF SYS(104)=2 THEN CHAIN "PRODENQ"

00120 IF SYS(104)=3 THEN CHAIN "CUSTENQ"

While within a program, at any task, a different task may only be selected while at an INPUT statement. The current task is "put to sleep" in the multi-task file. On returning to this task, it is awoken, and will continue with all files re-OPENed at their correct GPOS positions.

The task number is added to the value set by the BBTTYNO environment variable (if used) for any task other than the first one. It is up to the user to make sure that each workstation on the system has a unique BBTTYNO value that is at least the number of permitted multi-tasker sessions greater than its neighbor.

Note: Under Windows there is no LOCKing between tasks.

If a task is terminated, then it cannot be restarted as that task is "dead". The task can only be started again by exiting U/BL altogether and starting from scratch. When a task becomes deactivated it will not release any files it holds for its own exclusive use, that is, OPENed in modes 0, 1 or 2.

U/BL can be invoked without the multi-task facility. If this environment variable's setting is changed, then the change must be made before U/BL is invoked.

This environment variable cannot be changed by a $PUTENV statement.


BBNEWLIST

Description

Setting the BBNEWLIST environment variable to Y will turn on U/BL's physical line numbers, which can be used to LIST program lines for editing. The $L command can also be used to do this.

As with the $L command, the physical line prompt '%' will be displayed when U/BL is invoked with BBNEWLIST set to Y.

This environment variable can be changed by a $PUTENV statement.

Example

BBNEWLIST=Y

See also

$L

BBPROMPTP


BBNEWRECZERO

Description

Set the BBNEWRECZERO environment variable to 'N' if you want the Linked Available Files control information to be stored in the files FCB area, and a separate record 0 control record to not be maintained, when using the GETREC and DELREC statements.

Revisions of U/BL 2.20 and above provide full support for the GETREC and DELREC statements under SuperDOS emulation. Previously these two statements were only partially supported, as under this emulation mode they did not maintain a "record0" control record. Instead the statements relied on storing the relevant information in the files File Control Block (FCB). With U/BL 2.20 and above these statements now maintain the Linked Available files control information in the "record 0" control record which is the first record in the file. In common with SuperDOS Business BASIC, the GETREC and DELREC statements do not update the maximum and next record pointers held in the FCB as, information held in record 0 of the file is independent to that held in the FCB. Prior to U/BL 2.20 and above the Linked Available Files control information was stored in the files FCB area and a separate record 0 was not maintained.

For backward compatibility, the environment variable BBNEWRECZERO has been provided. Set this to 'N' to replicate the original functionality.

Example

BBNEWRECZERO=N


BBNFILES

Description

The BBNFILES environment variable defines the maximum number of global files that can be opened.

The handling of file exclusion has been improved to use less memory. This has also resulted in a slight performance improvement in file OPENing.

Only one control structure is required for each file OPENed, independent of the number of users on the system. Previous versions of ublmon set up shared memory so that each file OPENed by each user required a control structure. The minimum number of global files in use, independent of the number of users, is set at 100. This can be increased using either the environment variable BBCHAN=n, or BBNFILES=n, or the following switch, whichever is the greater:

ublmon -f<n>

Note: If BBEXCL is set to 'N', then exclusive file control is not maintained.

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

BBNFILES is one of a group of environment variables that control the product's configuration. Other environment variables that configure the shared memory are:

BBNJOBS | Defines the number of background jobs
BBNLOCKS | Defines the maximum number of locks
BBSMEMORY | Defines the size of the shared memory for user use
BBSHLIB | Defines the size of the shared procedures memory library.

Some of these settings can also be determined by switches to ublmon, the Monitor Program, as:

ublmon -j<n> -l<n> -f<n> -m<n>

for background jobs, locks, files and memory respectively.

Example

BBNFILES=200

See also

BBNJOBS

BBNLOCKS

BBSHLIB

BBSMEMORY


BBNJOBS

Description

The BBNJOBS environment variable defines the number of background jobs available. The default number is 25% of the Licenced User Number (LUN), with a minimum of 4 background jobs. BBNJOBS may be set up to any value. It is not limited by the LUN, and up to 512 concurrent background jobs are permitted.

If this environment variable is changed after the U/BL Run-time has been started, then the Run-time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

Example

BBNJOBS=100


BBNLOCKS

Description

The BBNLOCKS environment variable defines the number of locks available. The default is 50.

The maximum value for BBNLOCKS is 128 on Windows based systems. Under UNIX the maximum value is 160, but this only applies if you are using shared file (there is no effective limit if using shared memory).

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

Example

BBNLOCKS=100


BBNOOPT

Description

The BBNOOPT environment variable controls U/BL's use of its screen optimization code. If screen control characters are sent directly to the screen, then this can affect U/BL's screen optimization and cause the output to become garbled. Setting BBNOOPT to Y will switch off U/BL's screen optimization and characters will be sent to the screen even if U/BL considers them to be there already.

It is recommended that the environment variable BBOPTIMISE is used rather than BBNOOPT, as it provides greater control of screen optimization

This environment variable cannot be changed by a $PUTENV statement.

Example

BBNOOPT=Y

See also

BBOPTIMISE


BBNOGUIBOX

Description

If the BBNOGUIBOX environment variable is set to Y, then the BOX command will work as it would without -g set when U/BL is in -g mode. It does not effect any other windowing statement.

Example

BBNOGUIBOX=Y


BBNOSTRIP

Description

If the BBNOSTRIP environment variable is set to Y, then the '$' or '@' symbol will not be stripped off the printer name when it is passed to the operating system's print spooler.

This environment variable can be changed by a $PUTENV statement.

Example

BBNOSTRIP=Y


BBNOUSCORE

Description

The BBNOUSCORE environment variable controls the use of underscores in certain U/BL statements.

It is no longer necessary to precede U/BL statements with an underscore. Commands such as _WINIT will have the underscore removed when the program is ENTERed.

This action can be avoided by setting the environment variable BBNOUSCORE to N. This will make U/BL act like UBB, insisting on underscores.

Note: U/BL commands such as EDIT and LSTRIP are underscore commands, so if BBNOUSCORE is set to N these commands will have to be preceded with an underscore.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBNOUSCORE=N

See also

EDIT

LSTRIP


BBNOWRAP

Description

By default word wrapping is ON when displaying Help files. Setting the BBNOWRAP environment variable to Y makes the default "no word wrap".

This environment variable can be changed by a $PUTENV statement.

Example

BBNOWRAP=Y


BBNULLFILL

Description

The BBNULLFILL environment variable can be used to control whether or not a file is null filled if a POSITION FILE statement goes past the end of the file.

BBNULLFILL defaults to Y, in which case the file will be null filled. If set to N, the file will still have its end of file marker moved to the new position, but the gap between the end of the file's "valid" data and the new end of file will not be null filled.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBNULLFILL=N


BBOPTIMISE

Description

The BBOPTIMISE environment variable allows greater control over screen optimisation than the BBNOOPT environment variable.

The BBOPTIMISE environment variable is a bit mask which allows greater control over U/BL's screen optimization than that provided by he BBNOOPT environment variable. It is, therefore, recommended that this environment variable is used in preference to he BBNOOPT environment variable.

The bit settings for the BBOPTIMISE environment variable are as follows:

Bit

Description

1

This bit enables cursor optimization. If the cursor is positioned to a location repeatedly, then U/BL will not send the cursor position sequence more than once. Also, U/BL will try to find shorter sequences to do the same thing such as using the "bol" (beginning of line) entry in the Terminal Definition File (TDF) if it can.

2

If characters are PRINTed to the screen which are already there, then U/BL will not display them if a cursor positioning sequence would involve less characters being sent. For example, PRINT @(-30);"ABC DEF" would be converted internally to have the same effect as PRINT @(-30);"ABC";@(1,14);"DEF" If the following line was then executed PRINT @(-30);"ABC DEF" then no output would be sent to the screen as the characters are already there.

3

This is an unusual bit since it increases the amount of characters that are sent to the screen. It will make U/BL use <CR><LF> and the PRINTing of spaces instead of cursor positioning sequences. Generally, spaces are PRINTed to achieve horizontal movement, but if there are already characters on the screen on that row, then they will be re-displayed to achieve the desired column. This feature is used for applications that use print-pass-through, since printers will not be able to "understand" cursor positioning sequences.

4

Forces a PRINT @(row,col) to issue the cursor positioning escape sequence. Otherwise U/BL will ignore PRINT @'s when the cursor is already at the given location.

The default setting for BBOPTIMISE is 3. A typical setting for applications that use print-pass-through would be BBOPTIMISE=5. This sets bits 1 and 3, so the amount of cursor positioning would be at a minimum.

16

Similar to STMA 6,102 - transparent mode. Handy for DG terminals with strange escape sequences being sent.

32

Optimize screen wrapping so that "autowrap" is heavily relied on. This setting must have autowrap set correctly for the terminal type.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBOPTIMISE=5

See also

BBNOOPT

TDF KEYWORDS


BBOSCALLS

Description

This environment variable specifies the location of the BBOSCALLS control file.

This file restricts the system calls that can be made from U/BL, explicitly listing those system calls that U/BL is or is not allowed to run. Those commands that you want to allow U/BL to run are listed in this file on lines starting with a '+'. The commands which must not be run (for instance, commands which may cause a problem in U/BL Windows NT client-server architecture) are listed on lines starting with a '-'. In addition, a wildcard character is allowed '*' so that all commands can be allowed or disallowed. For example, if the BBOSCALLS file contains:

-*

+DIR

+COPY

+PRINT

U/BL will not attempt to $EXECUTE any commands apart from PRINT, COPY, or DIR. The contents of the BBOSCALLS file are not case sensitive on Windows. Under UNIX the contents of the BBOSCALLS file are case-sensitive (since UNIX is a case-sensitive operating system).

The default behavior of U/BL (if the BBOSCALLS file is not defined) is to allow all commands to be $EXECUTEed.

The use of the BBOSCALLS file is particularly important when running U/BL under Windows, due to the client-server architecture in use. Unlike UNIX there is no direct communication between U/Gi and the operating system on the server. The Input/Output stream sent from U/Gi to the server is only visible to the U/BL job that is running. The stream cannot be redirected to or from any other process started on the server. This means that any external program called from U/BL (via the STME 19 or $EXECUTE statements) will have to run on the desktop of the server machine.

Example

BBOSCALLS=C:\ubl\misc


BBOSKLOCK

Description

The BBOSKLOCK environment variable can be set to Y to enable a different locking method for index operations (KDEL, KADD, and so on) which is much quicker than the usual "table" locking method used by U/BL. If used, then it must be set before the runtime is started.

Instead of modifying a shared file to indicate that a file is locked, U/BL will use an operating system service to lock the file. The only danger in using operating system locks is that a program may use the U/BL LOCK statement to prevent an index operation. This will no longer work since the index operation will use a different locking mechanism. Also ublmon cannot be used to display outstanding locks.

If a machine crashes and leaves a lock active, re-booting the PC will clear the lock. This was not true of table locks which had to be cleared manually with ublmon.

BBOSKLOCK defaults to N and is read by ublmon when creating the shared file. U/BL processes will examine the share file to see which type of lock to use. U/BL itself does not examine the value of BBOSKLOCK. ublmon displays the type of lock active. To change from table locks to operating system locks set BBOSKLOCK=Y, then use ublmon to kill and then re-start the run-time.

If this environment variable's setting is changed, then the change must be made before the runtime is invoked. This environment variable cannot be changed by a $PUTENV statement.

Example

BBOSKLOCK=Y


BBOUTDEV

Description

The BBOUTDEV environment variable defines the default output device returned by STMA 9,3,string$. The standard default is LPT.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBOUTDEV=LPR

  * stma 9,3,dev$

  * ;dev$

LPR


BBOVERFLOW

Description

The BBOVERFLOW environment variable is used to ensure that all calculations are carried out in quad precision regardless of the setting of the BBPRECISION environment variable.

To enable this feature set BBOVERFLOW=N. The default is BBOVERFLOW=Y where calculations will be range checked to ensure that they fall within the precision indicated by BBPRECISION.

BBOVERFLOW can also be set to F for full overflow checking. This will cause U/BL to generate an arithmetic error (error 16) if any intermediate part of a calculation goes outside of the precision range.

For example, if BBPRECISION is set to 4 and BBOVERFLOW has the following settings:

BBOVERFLOW=N | A=2^31 | => No error
BBOVERFLOW=Y | A=2^31 | => Error 16
BBOVERFLOW=F | A=2^31 | => Error 16
BBOVERFLOW=N | A=2^31/2 | => No error
BBOVERFLOW=Y | A=2^31/2 | => No error
BBOVERFLOW=F | A=2^31/2 | => Error 16

This environment variable can be changed by a $PUTENV statement.

Example

BBOVERFLOW=N

See also

BBPRECISION


BBOVERWRITE

Description

If the BBOVERWRITE environment variable is set to "Y", a warning message will be displayed if an existing program line is overwritten whilst developing at the '*' prompt. For example, if BBOVERWRITE is set to "Y", and the user is editing a program line as follows:

* list

00010 DIM A$[10],B$[10],C$[10]

00020 FOR I=1 TO 10

00030 GOSUB 1000

00040 NEXT I

00050 IF ER THEN STOP

* 40 ;er

the following warning message is displayed:

% Line 40 being overwritten.

Note: The line will still be overwritten.

The default setting is BBOVERWRITE=N. This environment variable can be changed by a $PUTENV statement.

Example

BBOVERWRITE=Y


BBPACKERR

Description

If the BBPACKERR environment variable is set to Y, then the PACK and UNPACK statements will perform reduced error checking. For example, PACK will not generate an error if an attempt is made to pack a number into a number of bytes which are too small for it to fit into. Also, a PACK statement which attempts to write past the end of the current length of a string will not generate an error.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPACKERR=Y


BBPAGE

Description

By default the BBPAGE environment variable is set to Y which filters the LISTing of programs to the screen. To disable this feature, set BBPAGE to N

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPAGE=N

See also

LIST


BBPATCH

Description

The BBPATCH environment variable is a bit mask which will hold the number of a patch designed to work around a bug in the operating system. Users will be notified which number applies to which patch as necessary.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPATCH=1


BBPATH

Description

The BBPATH environment variable provides a global search path for program source files, program SAVE files and data files after the current working directory is searched. If a file is OPENed in a mode where the file must or may exist, for example, mode 0, then it is first looked for in the current directory under the directory defined by BBROOT and then searched for in the directory(s) defined by BBPATH. Each directory in the list is separated by a colon or semi-colon under UNIX but only a semi-colon under Windows (because Windows uses the ':' for drive specification).

Logical file OPENing uses BBPATH. If the '.VL' cannot be resolved from the BBLINKS file then BBPATH is traversed. Both the '.VL' and '.DB' files must exist in the same directory.

BBPATH, BBSEARCH and BBSEARCH01-20 all perform the same function, but BBPATH takes precedence. BBPATH is limited to a maximum setting of 255 characters, including the BBPATH=. If your application needs a longer BBPATH than the permitted maximum, you can split the directories between BBPATH, BBSEARCH and BBSEARCH01-20. As BBPATH takes precedence, it is suggested that your most frequently used directories are specified by it.

If an invalid directory or file is used in setting BBPATH, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBPATH contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBPATH=C:\ACCOUNTS\DATA1;C:\ACCOUNTS\DATA2

Under UNIX

BBPATH=/u/libdata:/u/data2

See also

BBPROGS

BBROOT

BBSEARCH

BBSEARCH01-20

BBSOURCE


BBPCHECK

Description

The BBPCHECK environment variable can be used to alter the treatment of an off-line printer when it is OPENed. The default is for the program to wait for the printer to become available. If BBPCHECK is set to 'N', then the Windows 'Device not ready' error message will be generated. The default is Y.

Note: Selecting anything other than the 'R'etry option on the Windows error will cause the operating system to terminate the current job.

This environment variable can be changed by a $PUTENV statement.

Example

BBPCHECK=N


BBPCLOSE

Description

The two environment variables, BBPOPEN and BBPCLOSE, allow you to to send header and trailer information to a device. When a device file is OPENed, for example, OPEN FILE[C,M],"@LPT"), the contents of the file pointed to by BBPOPEN are first sent to the device before any of the program's output. When the device-file is CLOSEed, the contents of the file pointed to by BBPCLOSE are sent to the device.

This is particularly useful for sending special settings to, say, a laser printer, via BBPOPEN, and then re-setting the default values, via BBPCLOSE, after the output is complete.

The maximum length of both files containing the control sequences (the length of the sequences themselves) is 128 bytes.

If an invalid directory or file is used in setting either BBPOPEN or BBPCLOSE, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBxxxxx contains invalid directory/file <pathname>

where xxxxx will be OPEN or CLOSE as appropriate.

Note: These environment variables only apply to non-BBSPOOLed printers, as it is assumed that the BBPOOL script/batch file copes with any printer initialisation or resetting.

Both the BBPOPEN and BBPCLOSE environment variables may be altered at run-time by using the $PUTENV statement.

Example

Under Windows

BBPOPEN=C:\USER\UBL\PRTSTART

BBPCLOSE=C:\USER\UBL\PRTCLOSE

Under UNIX

BBPOPEN=/user/ubl/prt_start1

BBPCLOSE=/user/ubl/prt_close1


BBPDF

Description

The BBPDF environment variable must be assigned to the name of a file which contains the definition of all of the system printers' control sequences. The BBPDF file can be regarded as a "TDF for printers" as it declares the control functions that each type of printer will use. The following keywords may be used in a BBPDF file:

@(-nnn) | A sequence of 2 digit hex numbers, nnn in the range 100-119. This specifies a user-defined escape sequence that is actioned by PRINT @(-nnn) command. The sequence is used whenever the relevant PRINT @(-nnn) is directed to a printer with the same type as the one associated with the definition, that is, the same printer type as that specified by the previous type keyword in the BBPDF file.
init | A sequence of 2 digit hex numbers. This specifies the escape sequence directed to a printer when that printer is first OPENed. The sequence is used whenever the relevant PRINT @(-nnn) is directed to a printer with the same type as the one associated with the definition, that is, the same printer type as that specified by the previous type keyword in the BBPDF file. Use of this keyword performs much the same function as the BBPOPEN file. Note that the init sequence is not used by print-pass-through printers.
rem | If rem is the first entry in a pdf line, then the line will be treated as a comment and its contents ignored.
term | A sequence of 2 digit hex numbers. This specifies the escape sequence directed to a printer when that printer is CLOSEd. The sequence is used whenever the relevant PRINT @(-nnn) is directed to a printer with the same type as the one associated with the definition, that is, the same printer type as that specified by the previous type keyword in the BBPDF file. Use of this keyword performs much the same function as the BBPCLOSE file. Note that the term sequence is not used by print-pass-through printers.
type | A 1 digit decimal value. This keyword specifies that the definitions that follow (up to the next type keyword) apply to any printer whose numeric type (in BBPTYPE) matches the number following the type keyword.

The contents of a typical BBPDF file, which is in ASCII text format, will look like:

type 1

rem 24 pin, Epson compatible line printer

init 1b,5b,.....

term 1b,5b,.....

@(-100) 1b,5b,.....

@(-101) 1b,5b,.....

:

:

@(-119) 1b,5b,....

type 2

:

:

The BBPDF file defines all the control sequences associated with each type of printer supported on the system. In order for this file to be used, the BBPTYPE environment variable must also be set. Assuming that BBPTYPE is set, whenever a PRINT @(-nnn) is issued to an OPEN printer (and nnn is in the range 100-119), the escape sequence sent to the printer is selected from the BBPDF file, based on the printer type (determined from the BBPTYPE file).

This environment variable cannot be changed by a $PUTENV statement.

Example

With the following program:

00010 OPEN FILE[0],"PRN1"

00020 PRINT FILE[0],@(-110)

if the file specified by BBPDF contains:

Type 1

init 50,72,69,6e,74,65,72,20

rem Above entry is hex for the word "Printer"

@(-110) 54,79,70,65,20,31

rem Above entry is hex for "Type 1"

Type 2

init 50,72,69,6e,74,65,72,20

rem Above entry is hex for the word "Printer"

@(-110) 54,79,70,65,20,32

rem Above entry is hex for "Type 2"

and the file specified by BBPTYPE contains:

PRN1 2 DIRECT

PRN2 2 DIRECT

PRN3 1 DIRECT

PRN4 2 SPOOLED

@HP-LJ4 5 SPOOLED

then the output directed to the printer will be "Printer Type 2". If the BBPTYPE file defined printer "PRN1" as being of type 1, then the output would have been "Printer Type 1".

See also

BBPPTTYP

BBPTYPE


BBPER

Description

The BBPER environment variable is used to specify the name of a file which contains a list of the devices that should be spooled to using BBSPOOL. If BBPER is not set up, then U/BL will spool all files which begin with a '$' or an '@' symbol (plus Windows device files on Windows based systems).

If the file specified by BBPER exists, then only those devices named in that file will be spooled to using BBSPOOL. U/BL will ignore BBPER if it cannot read the file. The devices names listed in the file must be exact matches for the file names used in the program. For example, if the BBPER file contains the following:

$LPT1

$LPT2

then OPENing "$LPT1" or "$LPT2" will cause the output to those devices to be sent to them via BBSPOOL. Output to "$LPT" will be sent directly to the device, as its name isn't mentioned in the BBPER file.

This environment variable cannot be changed by a $PUTENV statement.

Examples

Under Windows

BBPER=C:\USER\UBL\SPRINTS

Under UNIX

BBPER=/user/ubl/sp_printers

See also

BBSPOOL


BBPHYSCHAN

Description

The BBPHYSCHAN environment variable can be used to select the number of physical channels available to U/BL programs. The default is 32.

The operating system may impose a lower limit, so make sure that the operating system has been configured with at least the number of physical channels specified by the BBPHYSCHAN environment variable. Configure the operating system's number of physical channels to at least 7 more than BBPHYSCHAN's setting, as U/BL uses some of the physical channels itself. It is not essential to re-configure the operating system, but BBPHYSCHAN may have no effect if there are not enough channels.

Files will be de-activated once U/BL runs out of physical channels, so performance may be enhanced by setting BBPHYSCHAN to more than 32 if your application opens many files at the same time. Use the $F command to see which files have been de-activated (an '*' will be displayed next to de-activated channel numbers).

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPHYSCHAN=40


BBPOPEN

Description

The two environment variables, BBPOPEN and BBPCLOSE, allow you to to send header and trailer information to a device. When a device file is OPENed, for example, OPEN FILE[C,M],"@LPT"), the contents of the file pointed to by BBPOPEN are first sent to the device before any of the program's output. When the device-file is CLOSEed, the contents of the file pointed to by BBPCLOSE are sent to the device.

This is particularly useful for sending special settings to, say, a laser printer, using BBPOPEN, and then re-setting the default values, using BBPCLOSE, after the output is complete.

The maximum length of both files containing the control sequences (the length of the sequences themselves) is 128 bytes.

If an invalid directory or file is used in setting either BBPOPEN or BBPCLOSE, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBxxxxx contains invalid directory/file <pathname>

where xxxxx will be OPEN or CLOSE as appropriate.

Note: These environment variables only apply to non-BBSPOOLed printers, as it is assumed that the BBPOOL script/batch file copes with any printer initialisation or resetting.

Both the BBPOPEN and BBPCLOSE environment variables may be altered at run-time by using the $PUTENV statement.

Example

Under Windows

BBPOPEN=C:\USER\UBL\PRTSTART

BBPCLOSE=C:\USER\UBL\PRTCLOSE

Under UNIX

BBPOPEN=/user/ubl/prt_start1

BBPCLOSE=/user/ubl/prt_close1


BBPOUND

Description

The BBPOUND environment variable converts hash to sterling pound. The default is N.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPOUND=Y


BBPPTTYP

Description

The BBPPTTYP environment variable defines the 'printer type' of the printer used when the terminal is in print-pass-through mode. While in pass-through-mode, the escape sequences sent by any @(-nnn) command (nnn in the range 100 to 119) will be selected from the BBPDF file based on the value of BBPPTTYP.

This environment variable cannot be changed by a $PUTENV statement.

Example

If , BBPPTTYP=2, then the output for the program:

00010 PRINT @(-61) : Print-pass-through on

00020 PRINT @(-100)

00030 PRINT @(-62) : Print-pass-through off

00040 PRINT @(-100)

will be:

Starting PPT ---+

To a type 2 printer |-- Passed through to the printer

Ending PPT |

To the screen ---+

if BBPDF contains:

type 1

:

:

type 2

@(-100) 54,6f,20,61,20,74,79,70,65,20,32,20,70,72,69,6e,74,65,72

rem Above line sets @(-100) to echo "To a type 2 printer"

:

and the BBTERM contains:

:

:

@(-61) 53,74,61,72,74,69,6e,67,20,50,50,54

rem Above line sets @(-61) to echo "Starting PPT"

@(-62) 45,6e,64,69,6e,67,20,50,50,54

rem Above line sets @(-62) to echo "Ending PPT"

@(-100) 54,6f,20,74,68,65,20,73,63,72,65,65,6e

rem Above line sets @(-100) to echo "To the screen"

See also

BBPDF

BBPTYPE


BBPRECISION

Description

The BBPRECISION environment variable is used to signify the precision of numeric variables that the applications use. It can be set to 4, 6 or 8 and ensures that numeric variables will be signed correctly when using CHR$ and SHFT.

If an attempt is made to use an invalid setting for BBPRECISION, U/BL will display the following warning message when it is invoked (U/BL will start up as normal after displaying the message):

WARNING: BBPRECISION invalid (<invalid setting>)

This environment variable can be changed by a $PUTENV statement.

Note: If the BBLARGEFILES environment variable is set to Y, then the BBPRECISION environment variable must be set to 8. This environment variable can then not be changed by the $PUTENV statement.

Example

BBPRECISION=4

This will ensure that all 4 byte numeric variables will be signed correctly when using CHR$ and SHFT.

See also

BBOVERFLOW


BBPREFIX

Description

If the BBPREFIX=xxxx environment variable is set, where 'xxxx' can be any ASCII character sequence up to four characters long, then all LOCKs (including automatic LOCKs) will be specified with the multiple character prefix 'xxxx' preceding the normal LOCK string. This allows multiple copies of the same application system to concurrently operate on the same hardware. For example, a 'test' and 'live' system of the same application with the same LOCK conventions can process concurrently, with the 'test' system BBPREFIX set.

Note: The use of BBPREFIX results in a reduction in the number of characters used from the name supplied to the LOCK statement. If BBPREFIX is set to two characters, U/BL will use the first eight characters from the name supplied to the LOCK statement and prefix them with the value of BBPREFIX to produce the string that will be added to the LOCK table. If BBPREFIX is set to its maximum width of four characters, U/BL will only use the first six characters supplied to the LOCK statement (so that the final string used is always no more than ten characters in length).

The environment variable BBGLOBLOCK can be used to override the setting for BBPREFIX. BBGLOBLOCK defines the full path name of a text file which contains a list of all the global locks which can be applied by the application.

When U/BL is invoked, this file will be read into memory for optimum performance. When a lock request is made to U/BL's lock handler, this table will be searched. If an exact match is found, then the current value of the environment variable BBPREFIX is not added to the file name.

BBPREFIX can be changed by a $PUTENV statement, but note that if the BBGLOBLOCK environment variable is set, then changes to BBPREFIX made via a $PUTENV statement will not have any affect.

Example

BBPREFIX=T : Test System

See also

BBGLOBLOCK


BBPRINTCR

Description

If the BBPRINTCR environment variable is set to "Y", then any carriage return characters which are written to a file will not be converted to new-line characters. The following code will write a line of text to a file, followed by a carriage return and another line of text:

00030 PRINT FILE[OUT],"Testing<13>";

00040 PRINT FILE[OUT],"_______"

The resulting output will have the word "Testing" underscored.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPRINTCR=Y


BBPRINTTRUNC

Description

If the BBPRINTTRUNC environment variable is set to Y, the output from PRINT FILE commands will be truncated as if they were being printed to the screen.

The truncated length will be BBLINE characters, if BBLINE is valid. The default length is 132 characters.

Note: If the environment variable BBEXTENSION is set to SDOS, the truncation length is 5000 characters.

If an STMA 6,13 has been issued, the truncation length will be 256 characters. A subsequent STMA 7,13 will reset the truncation length to 132 characters.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBPRINTTRUNC=Y


BBPROGS

Description

The BBPROGS environment variable must be assigned to the directory(s) where the SAVEd/REPLACEd programs are resident. If this variable is missing the current directory is assumed. Each directory in the list is separated by a colon or semi-colon under UNIX but only a semi-colon under Windows (because Windows uses the ':' for drive specification).

As there are SAVEd programs in the product's System Software directory, this directory must be included in the BBPROGS search list. When a program is SAVEd or REPLACEd, it will always be placed in the first directory specified by BBPROGS.

If an invalid directory or file is used in setting BBPROGS, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBPROGS contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBPROGS=C:\UBL\ACCOUNTS\PROGS;C:\USER\UBL

Under UNIX

BBPROGS=/user/progs:/u/progslib:/user/ubl

See also

BBLIB

BBPATH

BBROOT

BBSEARCH

BBSEARCH01-20

BBSOURCE


BBPROMPTL

Description

The BBPROMPTL environment variable can be used to define a string of characters which are to be used instead of the traditional '* ' prompt, that is, the prompt displayed when not in physical line mode.

The default '* ' prompt consists of an asterisk '*' and a space. This is so that code typed at the prompt isn't displayed right up against the asterisk. Since trailing and leading spaces are ignored in the BBENV file, leading and trailing spaces in BBPROMPTL's setting must be entered as an underscore '_'. U/BL will convert the first leading and last trailing underscores to spaces when it displays the prompt.

Note: The swap level is still displayed before the prompt when at swap level 1 or higher.

This environment variable can be changed by a $PUTENV statement.

Example

BBPROMPTL=U/BL>_

Sets the prompt to "U/BL> ". Note that the underscore has been converted to a space.

See also

$L

BBNEWLIST

BBPROMPTM

BBPROMPTN

BBPROMPTP


BBPROMPTM

Description

The BBPROMPTM environment variable can be used to define a string of characters which are to be used instead of the "Modify> " prompt when editing program lines.

The default "Modify> " prompt consists of the word "Modify", a right angle bracket (>) and a space. This is so that the prompt is indented and that code typed in at the prompt isn't displayed right up against the angle bracket. Since trailing and leading spaces are ignored in the BBENV file, leading and trailing spaces in BBPROMPTM's setting should be entered as an underscore '_'. U/BL will convert the first leading and last trailing underscores to spaces when it displays the prompt.

Note: The swap level is still displayed before the prompt when at swap level 1 or higher.

This environment variable can be changed by a $PUTENV statement.

Example

BBPROMPTM=Editing>>_

Sets the prompt to "Editing>> ". Note that the underscore has been converted to a space.

See also

BBPROMPTL

BBPROMPTN

BBPROMPTP

.M


BBPROMPTN

Description

The BBPROMPTN environment variable can be used to define a string of characters, which are to be used instead of the " > " prompt when in one of the .N line editing modes.

The default " > " prompt consists of four spaces, a right angle bracket '>' and a space. This is so that the prompt is indented and that code typed in at the prompt isn't displayed right up against the angle bracket. Since trailing and leading spaces are ignored in the BBENV file, leading and trailing spaces in BBPROMPTN's setting must be entered as an underscore '_'. U/BL will convert the first leading and last trailing underscores to spaces when it displays the prompt.

Note: The swap level is still displayed before this prompt when at swap level 1 or higher.

This environment variable can be changed by a $PUTENV statement.

Example

BBPROMPTN=_ >>_

Sets the prompt to " >> ". Note that the first leading and last trailing underscores have been converted to spaces.

See also

BBPROMPTL

BBPROMPTM

BBPROMPTP

.N

.NA

.NB


BBPROMPTP

Description

The BBPROMPTP environment variable can be used to define a string of characters, which are to be used instead of the "% " prompt, that is the prompt that is displayed when in physical line mode.

The default "% " prompt consists of a percent sign '%' and a space. This is so that code typed in at the prompt isn't displayed right up against the percent sign. Since trailing and leading spaces are ignored in the BBENV file, leading and trailing spaces in BBPROMPTP's setting should be entered as an underscore '_'. U/BL will convert the first leading and last trailing underscores to spaces when it displays the prompt.

Note: The swap level is still displayed before the prompt when at swap level 1 or higher.

This environment variable can be changed by a $PUTENV statement.

Example

BBPROMPTP=&_

Sets the prompt to "& ". Note that the underscore has been converted to a space.

See also

$L

BBNEWLIST

BBPROMPTL

BBPROMPTM

BBPROMPTN


BBPTYPE

Description

The BBPTYPE environment variable must be assigned to the name of an ASCII text format file which contains the definitions of system printers. The file will look similar to this:

PRN1 | 2 | DIRECT
PRN2 | 2 | DIRECT
PRN3 | 1 | DIRECT
PRN4 | 2 | SPOOLED
@HP-LJ4 | 5 | SPOOLED

The file contains one line per printer. Each printer's definition consists of three parts: the name of the printer; its type; the method of its connection, that is, either direct or via BBSPOOL.

When BBPTYPE points to a definition file, whenever a file is OPENed, the filename (less all directory components) is tested against all the printer names listed in the BBPTYPE file. If no match is found, the file is regarded as not being a printer. On the other hand, if that printer is listed in the BBPTYPE file, the file is regarded as either a directly OPENed printer or as a spooled printer, that is, BBSPOOL is set.

The selection of the connection type depends on the third part of the printer description (if BBSPOOL is not set, or there is no connection information, the printer is assumed to have a direct connection).

In the respect that BBPTYPE identifies which files are spooled printers, the file performs a similar task to the BBPER environment variable. However, BBPTYPE has two distinct advantages over BBPER. The first is that it allows the specification of the files which are directly attached printers (rather than relying on the default rule of any file starting with a '$' or an '@' symbol being regarded as a printer).

The other advantage of using BBPTYPE is that it allows user defined PRINT @(-nnn) commands to be associated with a particular printer. The printer type listed in the BBPTYPE file associates a printer with a particular set of user defined @(-nnn) functions defined in the BBPDF file. When a PRINT FILE[C],@(-nnn) command is issued (to a channel on which a printer has been OPENed), the escape sequence sent is selected from the BBPDF file, based on the printer's type as defined in the BBPTYPE file.

Note: Normally, any user defined @(-nnn) sequences in the terminal definition file (TDF) will be sent to any file that they are printed to. If the file is listed in the BBPTYPE file, then the @(-nnn) sequences for that type in the BBPDF file take precedence.

This environment variable cannot be changed by a $PUTENV statement.

Example

With the following program:

00010 OPEN FILE[0],"PRN1"

00020 PRINT FILE[0],@(-110)

and the following BBPDF file:

type 1

@(-110) 54,79,70,65,20,31

type 2

@(-110) 54,79,70,65,20,32

and BBPTYPE specifying a file with the following contents:

PRN1 | 2 | DIRECT
PRN2 | 2 | DIRECT
PRN3 | 1 | DIRECT
PRN4 | 2 | SPOOLED
@HP-LJ4 | 5 | SPOOLED

then the output directed to the printer will be "Type 2". Had the BBPTYPE file defined PRN1 as being of type 1, then the output would have been "Type 1".

See also

BBPDF

BBPPTTYP


BBRAWOUT

Description

The BBRAWOUT environment variable allows 'raw' output of characters that are less than ASCII 31. By default, all characters less than 31 that perform a specific screen function are translated into the escape sequence that performs that function on the particular terminal being used.

For example, ASCII 2 is translated into 'End-Reverse-Video'. By setting BBRAWOUT=Y, it is possible to inhibit these translations, so that the 'raw-ASCII' value is actually sent to the screen. This feature can be particularly useful when using print-pass-through.

This environment variable can be changed by a $PUTENV statement.

Example

BBRAWOUT=Y


BBRDOS

Description

The BBRDOS environment variable supports the variations between Data General Business BASIC (RDOS) and the AOS/VS version. Currently the following features are switched on by setting BBRDOS=Y (the default being N):

  1. Support of RDOS implementation of TRUN$ - not terminating on

  2. Character Support of DEL-key processing with STMA 6,0/8 set.

  3. Support of PRINT TABs affecting INPUT statements.

  4. SYS(29) will return a unique number that is determined by the number of times the SYS(29) function has been accessed by all jobs.

If BBRDOS isn't set, or if it is set to N, then SYS(29) returns the processs' PID number plus a multiple of 1000. That multiple is determined by the number of times that the SYS(29) function has been accessed by that process.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBRDOS=Y


BBREDIM

Description

The BBREDIM environment variable allows reDIMensioning of strings > than original length.

Usually the reDIMensioning of string variables to a size larger than their original definition is not allowed. This environment variable, when set as BBREDIM=Y, removes this Data General Business BASIC imposed limitation.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBREDIM=Y


BBREMBAD

Description

The BBREMBAD environment variable is used when importing source code files into U/BL. If set to "Y", then any program lines which contain what U/BL considers to be syntax errors will be prefixed with "REM UNSUPPORTED". If BBREMBAD is set to "N", then any syntax errors will be reported on as normal.

This environment variable can be changed by a $PUTENV statement.

Example

BBREMBAD=Y


BBREMEDIT

Description

When using U/BL with U/Gi in GUI ('-g' graphical) mode, you can select a client based editor when using the U/BL EDIT command. This is achieved by using the BBREMEDIT and BBREMEDITOR environment variables.

To enable the remote editing functionality, set the BBREMEDIT environment variable to Y. If you then issue an EDIT command, U/BL will attempt to launch an editing session on the machine where the U/Gi client is running. To facilitate this, U/BL automatically transfers a copy of the current program to the client PC.

The value of the BBREMEDITOR environment variable is then used to determine the editing program (if BBREMEDITOR is not set, U/BL will attempt to use a remote copy of the program pointed to by the BBEDIT environment variable). Upon completion of the editing session, U/Gi will automatically transfer the updated source file back to the U/BL process which will then update the working storage in the usual manner.

Note: The BBREMEDIT environment variable is not applicable on Windows 2000, Windows NT and Windows 95/98. The remote editor is always used and can be specified by either the BBEDIT or the BBREMEDITOR environment variables. If both are set, the BBREMEDITOR environment variable will take precedence.

Example

BBREMEDIT=Y


BBREMEDITOR

Description

When using U/BL with U/Gi in GUI ('-g' graphical) mode, you can select a client based editor when using the U/BL EDIT command. This is achieved by using the BBREMEDIT and BBREMEDITOR environment variables.

To enable the remote editing functionality, set the BBREMEDIT environment variable to Y. The value of the BBREMEDITOR environment variable is used to specify the full pathname of the editing program which will be invoked. If the BBREMEDITOR environment variable is not set, U/BL will attempt to use a remote copy of the program pointed to by the BBEDIT environment variable.

Note: On Windows 2000, Windows NT and Windows 95/98 the remote editor is always used (the BBREMEDIT environment variable is not applicable) and can be specified by either the BBEDIT or the BBREMEDITOR environment variables. If both are set, the BBREMEDITOR environment variable will take precedence.

Example

BBREMEDITOR=C:\WINNT\SYSTEM32\NOTEPAD.EXE


BBRESOLVE

Description

Under normal conditions any file to be created, for example, mode 0, will be created in the current directory as opposed to resolving a link. If the BBRESOLVE environment variable is set to Y, this causes all file names to be resolved, using the links file defined by the BBLINK environment variable, before the creation takes place. However, with BBRESOLVE=Y, it must be noted that the links file will be traversed first for all file openings and this may have an adverse effect on performance.

Under operating systems that support symbolic links, for example, DG/UX, DEC Ultrix, IBM AIX3, BBRESOLVE=Y is implied if symbolic links are used rather than the BBLINK links table.

BBRESOLVE will also be set to "Y" if both the BBLINK and BBLINKTYPE environment variables are not set, or if BBLINKTYPE is set to PSEUDO or SYMBOLIC.

BBRESOLVE has to be set to "Y" for PSEUDO links or the link would not be resolved. The link file would be OPENed rather than the resolution file.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBRESOLVE=Y


BBRETRY

Description

The BBRETRY environment variable sets the number of retries for security key checking.

For those environments where a security key is required, then as a default the product will try three times to read the key before going into demonstration mode, if at start up, or aborting during processing. In certain circumstances it may be necessary for the retries to be increased and this is achieved by setting BBRETRY.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBRETRY=5


BBRETURN

Description

If the BBRETURN environment variable is set as BBRETURN=Y, then if an error or STOP causes a SWAPped program to drop to the '*' prompt, the application will return to the previous SWAP level.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBRETURN=Y


BBREUSE

Description

The BBREUSE environment variable allows empty index blocks to be reused by the maintenance of an empty block chain in record zero of the files. If BBREUSE is set to Y, U/BL will manage the empty index block chain as follows:

  • Root block (relative to zero) bytes 132 to 135 - byte address of the first empty block of the chain. Zero indicates an empty chain.

  • Empty block (relative to zero) bytes 0 to 3 - byte address of the next empty block on the chain. Zero indicates the end of the chain.

If using non-U/BL routines to read and maintain the empty index block chain, when a leaf block becomes empty it is added to the chain but U/BL also removes the key from the index control block which points to this block. As a result this block may also become empty (and is therefore added to the chain). In this way block removal may become recursive.

It is important to remove the control level keys, otherwise the empty block may still be accessed. For best results indexes should be reorganized first to remove blocks which are already empty.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBREUSE=Y


BBROOT

Description

The BBROOT environment variable must be assigned to the directory which forms the 'root' of the application(s) data directory structure. If this variable is missing the current directory is assumed.

The data can be organized in a hierarchical directory structure (to mirror the Data General Business BASIC environment). For example:

The 'root' of this data directory structure is \USER\DATA.

If the directory specified by BBROOT cannot be accessed, either because it doesn't exist, or you don't have access permissions to it, an error 9160 will be generated when you try to invoke U/BL and you will not be allowed to continue.

This environment variable cannot be changed by a $PUTENV statement.

Example

Under Windows

BBROOT=\USER\DATA

Under UNIX

BBROOT=/user/data

See also

BBHOME

BBPATH

BBPROGS

BBSEARCH

BBSEARCH01-20

BBSOURCE


BBSAVE

Description

The BBSAVE environment variable defines the action of the SAVE and REPLACE commands.

The SAVEV and REPLACEV commands save a program in memory, along with the contents of its variables, the GOSUB stack, and the position reached in the program for a CON statement to resume from.

The SAVE and REPLACE commands writes a program in memory but do not retain the contents of its variables, the GOSUB stack or the position reached for a CON statement to resume from, unless the environment variable BBEXTENSION is set to include B32 or the environment variable BBSAVE is set to "Y".

Setting the BBSAVE environment variable to Y, reverses the behavior of the SAVE and SAVEV and the REPLACE and REPLACEV command. The default is N.

This environment variable can be changed by a $PUTENV statement.

Example

BBSAVE=Y


BBSCR

Description

The BBSCR environment variable allows screen recording to be active always.

When running U/BL with BBEXTENSION set to B32, having BBSCR set to Y will make programs behave as though a $TURN_ON(SCREEN_RECORD) statement had been executed immediately prior to running the program. If running U/BL with BBEXTENSION set to SDOS, this variable must be set to Y if the $SCREEN_PAINT, $SCREEN_LOAD and so forth, statements are to be used.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSCR=Y


BBSCROLL

Description

The BBSCROLL environment variable is used to enable or disable U/BL's window scrolling.

On Windows platforms the default action is to enable scrolling within a U/BL window. On UNIX based platforms the default action is to disable scrolling.

Note: If this environment variable is set to Y on a UNIX platform, a performance overhead is incurred when using U/BL's windows statements. The impact of this will largely depend on the type of communications and terminal speed and so on. In many cases this may be viewed as too much of an overhead, so the option is not recommended for use.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSCROLL=Y


BBSDOSDATE

Description

The SuperDOS implementation of Julian dates differs from that used in other dialects of Business Basic. This environment variable was formally used to allow selection of the SuperDOS functionality for U/BL's Julian date routines without the need to set the environment variable BBEXTENSION to SDOS. The operation of the Julian date routines is now controlled at a more configurable level by the environment variable BBJULIANFLAGS. This variable has superseded BBSDOSDATE although for backwards compatibility BBSDOSDATE is still supported, it has the same affect as setting BBJULIANFLAGS=529. If both BBSDOSDATE and BBJULIANFLAGS are set in U/BL's environment, BBJULIANFLAGS takes precedence. Refer to the documentation on BBJULIANFLAGS.

Example

BBSDOSDATE=Y

This implies the setting BBJULIANFLAGS=529


BBSDOSPATH

Description

If the BBEXTENSION environment variable is set to include SDOS, then setting the BBSDOSPATH environment variable to Y will cause file names passed to the CHECK, SWAP, CHAIN, RUN, and LOAD commands to be interpreted as path names.

This only applies to file names which begin with a '!', '.', '\' (on a Windows based system) or '/' (on a UNIX based system). File names which start with any of these characters will be interpreted as path names and subsequent directory separators are treated as such. Otherwise, directory separators are treated as argument separators.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSDOSPATH=Y


BBSDOSPUFILL

Description

The BBSDOSPUFILL environment variable has been added to provide SuperDOS emulation of the PRINT USING L8 format. Under SuperDOS the fill character set up by the L8 command gets used in the F format, whereas this is not so under other forms of Business BASIC. Consider the following example:

DIM X$[10]

INPUT USING "","ENTER A NUMBER ",X$

LET X=VAL(X$,ER)

PRINT USING "L8_0,F6.2",X

PRINT

PRINT USING "L8_0,E6.2",X

PRINT

PRINT USING "L8_0,D6.2",X

END

Running the program produces the following results:

SuperDOS | U/BL
001.23 | 1.23
01.23 | 01.23
001.23 | 001.23

Setting the BBSDOSPUFILL environment variable to Y with the BBEXTENSION environment variable set to SDOS, results in the fill character replacing leading spaces in the F format. This produces the same results as under SuperDOS:

SuperDOS | U/BL
001.23 | 001.23
01.23 | 01.23
001.23 | 001.23

If both of these environment variables are not set then the spaces are not replaced, as can be seen in the first row of the original table.

Example

BBSDOSPUFILL=Y


BBSDOSSTMT

Description

The BBSDOSSTMT environment variable provides support for two other unpend characters. This emulates the enhanced functionality found when running with the SuperDOS run-time support module (BBEXTENSION=SDOS).

In order to define the 3 and 4 unpend characters, STMA 4 has been enhanced to include:

STMA 4,16,char

where char defines the 3 unpend character and STMA 4,17,char where char defines the 4 unpend character.

SYS(10) will be set to 1 when the 2, 3 or 4 unpend character is entered. A new SYS function, SYS(170), has been added and its return value will relate to the unpend key which was pressed:

Unpend key | SYS(170)
1 | 1
2 | 2
3 | 3
4 | 4

In order to determine the value of the 3 and 4 unpend characters, STMA 3 has been enhanced to include:

STMA 3,16,char

where char will hold the current value of the 3 unpend character and:

STMA 3,17,char

where char will hold the current value of the 4 unpend character.

The default values of the unpend characters are:

Unpend key | Default Value
1 | 10
2 | 13
3 | 27
4 | 11

Note: Primary or secondary IKEYs take precedence over any unpend keys where their values match. For example, the default value of the 3 unpend key is 27, which is usually used as the primary IKEY.

In future releases of U/BL, extra SuperDOS functionality may be made available via this environment variable without inheriting the nuances of the SuperDOS run-time.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSDOSSTMT=Y

See also

STMA 3

STMA 4

SYS(170)


BBSEARCH

Description

The BBSEARCH environment variable provides a global search path for program source files, program SAVE files and data files after the current working directory is searched. If the BBSOURCE, BBPROGS, BBROOT or BBPATH environment variables are specified then they take precedence over BBSEARCH.

This is typically used when large sets of files need to reside over different disks or file systems. Each directory in the list is separated by a colon or semi-colon under UNIX but only a semi-colon under Windows (because Windows uses the ':' for drive specification).

Logical file OPENing uses BBSEARCH. If the '.VL' cannot be resolved from the BBLINKS file then BBSEARCH is traversed. Both the '.VL' and '.DB' files must exist in the same directory. The BBSEARCH01-20 environment variable can be used to extend the number of directories, which will be searched.

BBSEARCH, BBSEARCH01-20 and BBPATH all perform the same function, but BBPATH takes precedence. BBSEARCH is limited to a maximum setting of 255 characters, including the BBSEARCH=. If your application needs a longer BBSEARCH than the permitted maximum, you can split the directories between BBSEARCH, BBSEARCH01-20 and BBPATH. As BBPATH takes precedence, it is recommended that you use it to specify your most frequently used directories.

If any invalid directories are used in setting BBSEARCH, the following message will be displayed for each invalid entry when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBSEARCH contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBSEARCH=C:\USER\DATA;C:\USER\PROGS;C:\USER\SOURCE DO

Under UNIX

BBSEARCH=/user/data:/user/progs:/user/source

See also

BBLIB

BBSOURCE

BBPROGS

BBROOT

BBPATH

BBSEARCH01-20


BBSEARCH01-20

Description

The BBSEARCH01-20 environment variables provide a global search path for program source files, program SAVE files and data files after the current working directory is searched. If BBSOURCE, BBPROGS, BBROOT or BBPATH are specified then they take precedence over BBSEARCH01-20.

They are typically used when large sets of files need to reside over different disks or file systems.

Each directory in the list is separated by a colon or semi-colon under UNIX but only a semi-colon under Windows (because Windows uses the ':' for drive specification).

Logical file OPENing uses BBSEARCH01-20. If the '.VL' cannot be resolved from the BBLINKS file then BBSEARCH01-20 is traversed. Both the '.VL' and '.DB' files must exist in the same directory.

BBSEARCH, BBSEARCH01-20 and BBPATH all perform the same function, but BBPATH takes precedence. BBSEARCHnn is limited to a maximum setting of 255 characters, including the BBSEARCHnn=. As BBPATH takes precedence, it is suggested that your most frequently used directories are specified by it.

If any invalid directories are used in setting BBSEARCH01-20, the following message will be displayed for each invalid entry when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBSEARCHnn contains invalid directory/file <pathname>

These environment variables can be changed by a $PUTENV statement.

Example

Windows based system:

BBSEARCH=C:\USER\DATA;C:\USER\PROGS;C:\USER\SOURCE

BBSEARCH02=C:\USER\TESTDATA;C:\USER\TESTPROG;C:\USER\TESTSRC

UNIX based system:

BBSEARCH=/user/data:/user/progs:/user/source

BBSEARCH06=/user/testdata:/user/testprogs:/user/testsource

Note: The nn in BBSEARCHnn does not have to be sequential, that is, you don't need to set up BBSEARCH01, BBSEARCH02 and BBSEARCH03 before you can set BBSEARCH04.

See also

BBLIB

BBSOURCE

BBPROGS

BBROOT

BBPATH

BBSEARCH


BBSEDIT

Description

Setting the BBSEDIT environment variable to N allows you to switch off the cursor key editing facility. This is particularly useful if you wish to support terminal types other than the basic types 6 or 8. The default is Y.

BBSEDIT=N, is implied by setting the terminal type to 6, using BBTTYPE=6, or when running in 'background' mode.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSEDIT=N

See also

BBTTYPE


BBSEMUNDO

Description

The BBSEMUNDO environment variable causes the UNIX kernel to keep track of all semaphore operations, used to gain exclusive use of the LOCK and job tables. If BBSEMUNDO=Y, then the operating system will clear any set semaphores in a process that terminates abnormally. This has been made configurable since an undo data structure will be maintained, by the operating system kernel, for each concurrent semaphore operation. The undo structure will be removed by the kernel after successful completion of the semaphore operation.

On some implementations of UNIX, the default number of semaphore undo structures is quite low. Hence a FATAL run-time error (9128) will be generated if the semaphore operation fails due to lack of undo structures. It is possible to increase the number of semaphore undo structures by modifying the necessary kernel parameter and re-linking the kernel.

On SCO UNIX, this parameter is called SEMMNU and its default value is 30, which is more than sufficient for most uses.

On DG/UX, the mnemonic is SEMUME and its default value is 10. Experience has shown this to be too low for typical multi-user systems, and it is recommended that it should be increased.

Note: BBSEMUNDO will have no effect if the test and set method of locking is being used. This applies to 386/486 UNIX, AViiON DG/UX, RS/6000 AIX and to those systems where BBTESTANDSET is set to Y.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSEMUNDO=Y

See also

BBTESTANDSET


BBSEQUENCE

Description

If the BBSEQUENCE environment variable is set to "Y", then it will cause U/BL to report any line number sequence errors which it encounters whilst a program's source code is being ENTERed.

Note: The lines will be put into the correct sequence and the message is only a warning.

This environment variable can be changed by a $PUTENV statement.

Example

BBSEQUENCE=Y


BBSHARE

Description

The BBSHARE environment variable denotes where to access the shared facilities file. UNIX operating systems provide shared memory facilities and therefore this file is not required. However, Windows LANs do require a shared facilities file.

The implications of a shared file or shared memory run-time are discussed in more detail in the section on Shared Facilities.

If an invalid directory or file is used in setting BBSHARE, the following message will be displayed when U/BL is started up:

WARNING: BBSHARE contains invalid directory/file <pathname>

U/BL will attempt to create the file but, if it cannot, an error code 9126 will be generated by ublmon followed by an error code 9158 from U/BL. If this happens you will not be allowed to continue with U/BL.

This environment variable cannot be changed by a $PUTENV statement.

Example

Under Windows

BBSHARE=\TMP\SHAREFIL


BBSHELL

Description

Occasionally the standard "system" call to enact BBSPOOL fails without returning an error and therefore the particular report is not printed. This is a problem with certain versions of UNIX shells (Bourne and 'C'). The shellscript identified by the environment variable BBSPOOL can be executed by the operating system using a different mechanism by using the BBSHELL environment variable:

BBSHELL=/bin/sh

This mechanism forks a new child process (identified by BBSHELL) to execute the spooling script. If BBSHELL is omitted from the environment then the script is passed to the shell via the "system" call. If an invalid directory or file is used in setting BBSHELL, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBSHELL contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

BBSHELL=/bin/sh

See also

BBSPOOL


BBSHLIB

Description

The BBSHLIB environment variable defines the size of the shared procedures memory library. Any number of common routines can be loaded into the shared memory library. BBSHLIB sets the size, in bytes, to accommodate these routines.

The U/BL Monitor utility on starting the Run-Time sets up the appropriate memory segment, by referencing this environment variable.

Note: Under Windows shared procedures are supported on the 32 bit version only.

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

Other environment variables that configure the shared memory are:

BBNJOBS | Defines the number of background jobs
BBNLOCKS | Defines the maximum number of locks
BBSMEMORY | Defines the size of the shared memory for user use
BBSHLIB | Defines the size of the shared procedures memory library.

Example

BBSHLIB=20000


BBSHLIBFILE

Description

Versions U/BL 2.10 and above support multiple, different copies of the U/BL shared procedures. Individual users (or groups of users) can use their own copy of the shared procedures by using a shared procedures file. Shared procedures can therefore be developed, tested or debugged using this method and not affect the main body of U/BL users (who will continue to use the 'official' copy held in the U/BL run-time).

To employ a separate, file-based set of shared procedures, simply start the U/BL job (or jobs if several sessions are to share a set of procedures undergoing development) set the BBSHLIBFILE environment variable to a pathname of a file to act as the storage for the non-global shared procedures.

The U/BL job (or the first U/BL job if multiple sessions are to be run) will then install the relevant shared procedures in the usual manner. These will be installed into BBSHLIBFILE (creating the file if necessary) and be made available to any U/BL task using that shared procedures file.

Example

BBSHLIBFILE=C:\ubl\ubl_sharefile


BBSIGNAL

Description

The BBSIGNAL environment variable can be set to allow IKEY handling to take place only on an INPUT statement. Some applications require the ability to INPUT special control character sequences, such as left and right arrow keys, and to detect the ESC key in tight program loops.

On open system terminals, special characters like left and right arrow also generate the ESC character. When used heavily, with the REPEAT key for example, they may action the IKEY handling routine.

BBSIGNAL can have one of the following settings:

BBSIGNAL=1 | Allows the primary IKEY to be raised only on an INPUT statement.
BBSIGNAL=2 | Allows the secondary IKEY to be raised only on an INPUT statement.
BBSIGNAL=3 | Both of the above.

BBSIGNAL is checked whenever STMA 4,6, set_value and STMA 4,7, set_value are executed. The environment variable BBABORT takes precedence over this environment variable.

This environment variable can be changed by a $PUTENV statement.

Example

BBSIGNAL=2

See also

BBABORT

INTERRUPT


BBSIGNON

Description

The BBSIGNON environment variable defines the name of the licence banner file.

Ensure that the banner file, which for the development copy of the product is included on the system diskette(s), is in the product's System Software directory, for example, \USER\UBL. It is called, for example, YOURBAN.BAN, the '.BAN' extension is always given and the exact name is detailed on your Transoft Licence Banner form.

The banner file controls the number of concurrent users licensed to use the product. If no banner file is found, then the product will use a default demonstration banner which allows it to run for 5 minutes in interactive development mode, that is, for command entries made at the '*' prompt, or for a limited number of processing steps when running U/BL programs, which is typically 15-30 minutes of significant processing.

This environment variable cannot be changed by a $PUTENV statement.

Example

Under Windows

BBSIGNON=\USER\UBL\YOURBAN.BAN

Under UNIX

BBSIGNON=/user/ubl/YOURBAN.BAN

See also

SYS(161)


BBSLEVEL

Description

The environment variable, BBSLEVEL=n where n is a numeric value in the range 1 to 7, determines the SuperDOS Business BASIC security level. This numeric value is returned from SYS(38) which under SuperDOS is the user's security level.

If an attempt is made to use an invalid setting for BBSLEVEL, U/BL will display the following warning message when it is invoked (U/BL will start up as normal after displaying the message):

WARNING: BBSLEVEL invalid (<invalid setting>)

Remember the environment variable BBEXTENSION=SDOS, must be set for SuperDOS Business BASIC.

This environment variable can be changed by a $PUTENV statement.

Example

BBSLEVEL=3


BBSLITCH

Description

If the BBSLITCH environment variable is set to Y, then when entering code, numbers in angled brackets (<nn>) greater than 255 are not converted to a char in the range 0-255, and are treated as entered in the string. By default the BBSLITCH environment variable is set to 'N'.

The BBSLITCH environment variable is not $PUTENVable.

Example

The following line of code:

10 PRINT "<1998>"

is normally regarded as:

10 PRINT "<203>"

This is because any string within angle brackets (<>) is regarded as a decimal value, to be output as a single character. The value in angle brackets is the ASCII value of the character to be displayed. If the BBSLITCH environment variable is set:

BBSLITCH=Y

Then the line in the example will be treated as entered in the string. For example:

10 PRINT "<1998>"

The <1998> is treated as 6 individual characters rather then the decimal representation of a single character.


BBSLITLIST

Description

The BBSLITLIST environment variable allows the user to specify which chars in the range 0-126 are LISTed as <nn> - instead of the ASCII character. BBSLITLIST requires a list of comma-separated decimal integers.

The BBSLITLIST environment variable is not $PUTENVable.

Example

If BBSLITLIST=60,62 the line:

10 PRINT "<60><62>"

is listed or treated as:

10 PRINT "<60><62>"

instead of:

10 PRINT "<>"


BBSLOCK

Description

Under UNIX

If set to Y, the BBSLOCK environment variable ensures that the SuperDOS Business BASIC based statements SLOCK, RREAD, RWRITE, RRNEXT, RWNEXT and SUNLOCK operate correctly.

Calls to these functions are not blocked if the specified file is already locked, but an error 30 - "Disk or magnetic tape timeout" - will be generated instead.

Additionally READLOCK is correctly supported under UNIX if the environment variable BBSLOCK is set to Y.

This environment variable cannot be changed by a $PUTENV statement.

Under Windows

Earlier revisions of U/BL for Windows did not support the READLOCK statement, owing to the Windows operating systems not providing a rich enough locking environment to allow a process to read a record that had an outstanding SLOCK on it.

Revisions of U/BL 2.20 and above have been enhanced to provide their own locking mechanism which allow a process to read a record that has an outstanding SLOCK on it. This allows the READLOCK statement to work in the same way as SuperDOS BBASIC. To activate this functionality the BBSLOCK environment variable must be set to TABLE on Windows platforms.

The drawback to this method is that there is a performance penalty, because U/BL's own locking mechanism involves writing the locking details to a file rather than to the physical memory.

Example

Under UNIX

BBSLOCK=Y

Under Windows

BBSLOCK=TABLE


BBSLOCKDELAY

Description

The BBSLOCKDELAY environment variable controls how long a read should be delayed when there is an outstanding SLOCK on the record being read. The default value is one second, and this is also the minimum value to which BBSLOCKDELAY can be set.

This environment variable can be changed by a $PUTENV statement.

Example

BBSLOCKDELAY=3

See also

BBSLOCKRETRY


BBSLOCKRETRY

Description

The BBSLOCKRETRY environment variable controls how many times a READ will be attempted on an SLOCKed record before the program exits to the '*' prompt with an error 9469 - Time out on SLOCKed record - increase BBSLOCKRETRY or set BBSLOCKRETRY=-1.

Setting BBSLOCKRETRY to -1 will cause the READ to retry endlessly.

This environment variable can be changed by a $PUTENV statement.

Example

BBSLOCKRETRY=5

See also

BBSLOCKDELAY


BBSMEMORY

Description

An area of shared memory is provided for access by programs. This area of memory is common to all jobs.

The BBSMEMORY environment variable defines the size of the global shared memory for user use in bytes. The default is 512 bytes. The following statements can be used to access the shared memory created by ublmon:

SHMSIZE (N) | Returns in 'N' the size of the user shared memory area
SHMREAD (X$) | Copies into X$ the contents of the shared memory.
SHMWRITE (X$) | Copies into shared memory the contents of X$.

Exclusive use can be achieved by using a LOCK statement:

LOCK 10, "SMEMORY", from, to

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be killed and re-started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

Example

BBSMEMORY=1024

See also

BBNFILES

BBNJOBS

BBNLOCKS

BBSHLIB


BBSOCKREUSE

Description

If the BBSOCKREUSE environment variable is set to 'Y' then the SOCKSERV command will mark sockets for address reuse whether the new or the old syntax for SOCKSERV is used.

Example

BBSOCKREUSE=Y

See also

SOCKSERV


BBSOURCE

Description

The BBSOURCE environment variable should be assigned to the directory(s) where the programs' source LIST files are resident. If this variable is missing the current directory is assumed.

Each directory in the list is separated by a colon or semi-colon under UNIX but only a semi-colon under Windows (because Windows uses the ':' for drive specification).

When a program is LISTed to a file, it will always be placed in the first directory specified by BBSOURCE. If an invalid directory or file is used in setting BBSOURCE, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBSOURCE contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

Under Windows

BBSOURCE=C:\USER\SLSOURCE;C:\USER\PLSOURCE

Under UNIX

BBSOURCE=/user/source1:/user/source2

See also

BBPATH

BBPROGS

BBROOT

BBSEARCH

BBSEARCH01-20


BBSPOOL

Description

The BBCONMAP environment variable allows output to printers to be redirected via any spooling system to any device. Use the environment variable BBPER to specify those devices which BBSPOOL should use if you want to restrict its use.

If the environment variable BBSPOOL exists and the printer defined by a $ or @ as the first character, for example, $LPT, @LPT, is opened, then the product creates a unique filename (with a '.LPT' extension). Subsequent output to the printer will be written to this file.

When the file is CLOSEd the shellscript (UNIX/Xenix) or batch.bat file (Windows) which BBSPOOL points to, will be executed and the unique file generated will be passed as the first parameter.

A second parameter will be passed to the shell script or batch file. This is the printer name specified in the U/BL OPEN statement. Under UNIX, the printer name is passed without any "$" or "@" and the quotes are stripped off. For example, $LPT becomes LPT. Under Windows the printer name is passed surrounded by quotes and with the "$" or "@" symbol. For example, @LPT is passed as '@LPT'.

If BBSPOOL is not set, then the default is that output will be sent direct to the printer file OPENed (the printer name minus the "$","@" - unless, under UNIX only, BBNOSTRIP is set).

Note: PRN is equivalent to LPT under Windows.

The environment variable can be modified dynamically by $PUTENV.

Examples

Under Windows

BBSPOOL=SPOOL.BAT

where SPOOL.BAT is a batch file and is in a directory in the PATH list. The contents of SPOOL.BAT could look something like this:

PRINT %1

U/BL uses the Windows PRINT utility. Make sure that this utility is initialized when your system is brought up by including the following entry in your equivalent of AUTOEXEC.BAT:

PRINT /D:<name of your default printer, for example, PRN>

Note: The first time that PRINT is actioned DOS asks which printer is required, with the default being PRN. After that all spooled print is directed to the same printer.

To overcome this deficiency of Windows, the product allows additionally the system defined printers to be addressed directly in the OPEN FILE statement. These are:

Device Addressed | Actual Printer Device
PRN | PRN
LPT | PRN
LPT1 | LPT1
LPT2 | LPT2
LPT3 | LPT3

Printers are likely to be addressed directly for special stationery requirements.

Under UNIX

BBSPOOL=spool

where 'spool' is a shellscript with an execute permission and is in a directory in the PATH list. The contents of 'spool' could look something like this:

cat $1 > /dev/lp1

or if $2="LPT1" then

cat $1 > /dev/lp0

However, it is possible to send the unique file ($1) to the UNIX spooler or any other spooling mechanism.

lp -d$2 $1

Note: To have $LPT print direct to a device, say, /dev/lp0 for pre-printed stationery line-up, then insert a link using UBLLINKU. For example:

  Link name...........: $LPT

  Resolution File Name:!/dev/lp0

By altering BBSPOOL, it is possible to process the temporary output file before printing. The name of the printer device is passed to the BBSPOOL shell script as the second parameter, so this can be used to select which set of mappings should be applied to the output file (which is passed to the shell script as its first parameter). The actual character mappings can be performed by the UNIX tr command. For example:

if [ "$2" = "LPT1" ]

then

cat $1 | tr `\212\213` `\213\212` | lp -d $2

else

lp -d $2 $1

fi

The above example, as a BBSPOOL shell script, would print the output file ($1) to the requested printer ($2) with the additional feature that if the printer had been LPT1, it would convert the characters <138> and <139>.

It is possible to set-up the UNIX spooling system (lp) to cope with the required mappings. However, as the method of achieving this will be slightly different from one version of UNIX to another, it is probably best if you refer to your UNIX manuals or support to see how this is done.

See also

$FLUSHPRT

BBCONMAP

BBMAPFILE

BBNOSTRIP

BBPER

BBSHELL


BBSTMA9_0

Description

The BBSTMA9_0 environment variable allows the user to specify the case, upper or lower, in which they wish the user's name to be returned by an STMA 9,0 statement. Set it to "U" for upper or "L" for lower case. The user name will be the one specified by the BBUSER environment variable.

The BBEXTENSION environment variable must be set to include B32 if you wish to use this environment variable.

This environment variable can be changed by a $PUTENV statement.

Example

BBSTMA9_0=L

See also

BBSTMA9_2


BBSTMA9_2

Description

The BBSTMA9_2 environment variable allows the user to specify the case, upper or lower, in which they wish the current program's name to be returned by an STMA 9,2 statement. Set it to "U" for upper or "L" for lower case.

The BBEXTENSION environment variable must be set to include B32 if you wish to use this environment variable.

This environment variable can be changed by a $PUTENV statement.

Example

BBSTMA9_2=L

See also

BBSTMA9_0


BBSTME10

Description

The BBSTME10 environment variable is used to maintain compatibility with UBB v3.01 when using the STME 10 statement on a channel that has been OPENed with a "!filename". We strongly recommend that users DO NOT use this feature for the following reason:

A UNIX process is limited to the amount of files it is allowed to open. For this reason, U/BL uses a concept known as 'channel reactivation' to allow a U/BL program to OPEN more files than the operating system allows.

A user who OPENs a hundred files in a program may think all of them are physically open, but behind the scenes U/BL will open and close the files as the user accesses the different channels, opening no more that 32 at a time at the operating system level. For this to work, U/BL needs to store information about each file the user has OPEN, such as the file name and its GPOS.

UBB v3.01 had a problem with channel reactivation in the situation where a user OPENs a "!filename". If the channel this file was OPENed on was deactivated (temporarily closed to make room for another file) and the user changes directory, the next time this channel is referenced, U/BL will reopen the same file name ("!filename"), but off course we are now in a different directory, so we OPEN the file in the wrong directory! The problem is also apparent in the CHFREEZE and CHREOPEN commands.

UBB v3.10 solved this problem by converting a "!filename" to a full DG style path name. Some users may find that their code relied on STME 10 returning a "!filename", and their code worked in v3.01. For this reason, setting BBSTME10=Y will make U/BL work in the same way as UBB v3.01.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSTME10=Y

See also

STME 10


BBSTMEHIDDEN

Description

Under UNIX, hidden files always start with the '.' character. Under Windows, the hidden aspect of the file cannot be determined from the name of the file as the hidden nature is supported by a file attribute. Whereas under UNIX, it is relatively easy to exclude hidden files when using STME 0 (the program need just ignore files starting with a '.') this is not so easy under Windows.

To combat this, setting the BBSTMEHIDDEN environment variable to Y causes the STME 0 statement to ignore any hidden files that match the supplied file specification. Setting BBSTMEHIDDEN=N (the default) does not hide hidden files from the program.

This environment variable can be changed by a $PUTENV statement.

Example

BBSTMEHIDDEN=Y


BBSTMT

Description

The BBSTMT environment variable stores the current program line in shared memory/file. The line number is displayed in the STMT column of ublmon's job table. It can be set to one of the following:

BBSTMT=Y | Reports the number of any numbered program lines and also reports the physical line (suffixed by the '%' character) for those lines which do not have a line number associated with them.
BBSTMT=R | Only reports the numbered program lines and reports zero if the line does not have a line number. Real line numbers are stored naturally within U/BL whereas physical line numbers have to be calculated, so this option is quicker than setting BBSTMT=Y if only real line numbers (if present) are required.
BBSTMT=P | Always reports the current line of the program in terms of the physical location in the program. This report appears in the job table as a number suffixed by the '%' character.
BBSTMT=F | This setting is only available in U/BL 5.00 onwards. It always reports the current line of the program in terms of the physical location in the program, but is faster than setting BBSTMT=P. When BBSTMT=F all the physical line numbers of a program are calculated and stored whenever a LOAD, SWAP, CHAIN, RUN, ENTER, ERASE, RENUM, or single line entry/deletion occurs. Using BBSTMT=P the current physical line is recalculated for each line, which can be relatively slow.

The effect of the various settings can be illustrated with the following example program:

00010 REM

REM

@Label REM

When run this program will be reported by UBLMon as having run, in turn, the following lines:

BBSTMT=R BBSTMT=Y BBSTMT=P BBSTMT=F (U/BL 5.00+)

10 10 1% 1%

0 2% 2% 2%

0 3% 3% 3%

The return of the INQUIRE statement has been amended when interrogating the job table. In versions of U/BL earlier than 2.30, the current line number for the job’s program was reported at bytes 53-54 of the job details packet.

With U/BL 2.30 and above, this original information is maintained (for backwards compatibility with old programs) and a new field has been added. This new field can be found at bytes 78-79 of the job packet. This area was formally the first 2 bytes of the free space, ‘filler’ entry in the job packet (this area has now correspondingly been reduced by two bytes to occupy the last 14 bytes of the packet).

If the U/BL job is running with BBSTMT=P or F, this new field will be primed with the physical location of the line that the current program is executing. If BBSTMT=Y, the new field contains the line number of the current line if it has one, otherwise it contains the physical position of that line within the program.

To distinguish whether or not the information relates to a line number or the physical position of the line, the value extracted from the original location and the value from the new field should be compared. If they are identical, the information indicates a line number, if they differ, the new field is the line’s physical position in the program.

The new field in the job packet is only valid with jobs running U/BL 2.30 and above. Interrogating this region of the packet for earlier versions of U/BL will have undefined results. To check whether any given U/BL job is running revision 2.30 or later, AND the job type (bytes 5-6) of the packet with 128. A true result indicates that the job is running revision 2.30 or later. The following is some example code for performing the relevant interrogation of the job packet. This code assumes the X$ string holds the returned information from an INQUIRE against the job tables and that X points to the start of the packet associated with the job we are interested in:

@JobPkt RFORM LJS16S16S10JJJS10S10LJS14

UNPACK @JobPkt, X$[X+5], PID, JOB_TYPE, NAME$,

PROG_NAME$, DEVICE$, SYS_4, SYS_9, LINE, BBUSER$, BBMACHINE$, STATUS, NEW_LINE, FILLER$

IF AND(JOB_TYPE,128) THEN

IF LINE= 0 THEN

LET LINE_NO = NEW_LINE \ PHYSICAL$="%"

ELSE

IF NEW_LINE <> LINE THEN

LET LINE_NO = NEW_LINE \ PHYSICAL$="%"

ELSE

LET LINE_NO = LINE \ PHYSICAL$=""

END IF

END IF

ELSE

LINE_NO = LINE

END IF

IF LINE_NO = 0 THEN PHYSICAL$=""

PRINT "LINE NO ="LINE_NO;PHYSICAL$

Example

BBSTMT=Y


BBSTRIP

Description

As in Data General's Business BASIC, the 8th bit of input characters is normally stripped off.

If the BBSTRIP environment variable is set to N, then 8 bit input characters are not stripped and are accepted. This is particularly required for foreign character sets. The default is Y to strip.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSTRIP=N

See also

BBCHAR


BBSTRIPLNO

Description

Setting the BBSTRIPLNO environment variable to Y will cause any program ENTERed to have its line numbers stripped automatically.

This environment variable can be changed by a $PUTENV statement.

Example

BBSTRIPLNO=Y

See also

LSTRIP


BBSXTRA

Description

If the environment variable BBEXTENSION is set to include SDOS, then string arrays are only recognized if the BBSXTRA environment variable has been set in your environment. This is because SuperDOS Business BASIC allows the numeric variable #1. Setting the BBSXTRA environment variable causes U/BL to no longer recognize the variable #1 (or any variable beginning with a "#" and a number).

Also, if BBEXTENSION is set to include SDOS, then if I=2 and #I=4, U/BL will see A$[#I] as A$[4] rather than A$[#2].

Note: This environment variable's setting has no effect on the SXTRA area of memory.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSXTRA=1000


BBSYS30

Description

The BBSYS30 environment variable allows bits in the result of a SYS(30) function to be modified. In use it is simply set to a 16-bit number which is logically ORed with the 'raw' result of SYS(30). This enables any bit to be set.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBSYS30=256

This forces the setting of the AOS/VS bit on a SYS(30).

See also

SYS(30)


BBSYS4INC

Description

When the BBSYS4INC environment variable is set, its value will be added to the normal return of SYS(4) if the job is a foreground job (a SYS(4) of -1 will always be returned as such).

Regardless of BBSYS4INC's setting, ublmon will always report the raw SYS(4) value (the value that would returned by SYS(4) if BBSYS4INC=0). This environment variable is particularly useful for applications that have been coded under the SuperDOS Business BASIC environment, hard-coding job number 1 to use PC escape sequences. The default value for BBSYS4INC is zero and only positive increments are allowed.

This environment variable can be changed by a $PUTENV statement.

Example

When the following program, SAVEd as EG:

00010 PRINT SYS(4)

00020 $PUTENV "BBSYS4INC","4"

00030 PRINT SYS(4)

is run:

ubl EG

it typically produces the output:

1

5

but:

ubl EG < /dev/null > output &

will produce the output:

-1

-1


BBSYS4SLOT

Description

This environment variable is used in conjunction with the BBTTYS environment variable.

BBTTYS is used to specify a file that contains a table which assigns SYS(4) values to device names.

When a new U/BL job connects to the U/BL runtime, the SYS(4) value allocated is the next available job slot number or the value specified in the BBTTYS file (if set). That is, if the BBTTYS file does not include an entry for the terminal from which you logon to U/BL, then the following warning message will be displayed:

WARNING: Terminal line (/dev/<line no>) not found in BBTTYS.

and that U/BL process will be assigned the next available job slot number for its SYS(4) value. This value may conflict with an entry in the BBTTYS file.

To prevent the slots allocated in the BBTTYS file from being taken up by jobs on devices not listed in the BBTTYS file, set BBSYS4SLOT to the number of slots allocated in the BBTTYS file.

For example, if BBSYS4SLOT=19 then the first 19 slots in the job table will be reserved for terminals listed in the BBTTYS file, any U/BL processes on other terminals will be placed at the end of the job table.

This environment variable cannot be changed using the $PUTENV command.

This environment variable must be set when the runtime is started but it doesn't need to be set in the environment for each U/BL process.

Example

BBSYS4SLOT=19

See Also

BBTTYS


BBTAB

Description

By default the tab setting in Help text files is every eight characters. Setting the environment variable BBTAB=n, sets the tabs to every n characters.

Example

BBTAB=5


BBTABWIDTH

Description

The BBTABWIDTH environment variable sets the tab spacing used by commas in PRINT statements. If BBTABWIDTH is not set, or if it is set to zero, then the commas will be treated as semi-colons, that is, the next character will be PRINTed in the next print position.

The tab width can also be interrogated or changed by the STMA 3,9,x and STMA 4,9,x statements respectively, where x is the current tab width/new setting.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBTABWIDTH=14

Note: 14 is Data General Business BASIC's default tab width.


BBTERM

Description

The BBTERM environment variable should be assigned to the name of the Terminal Definition File (TDF) which denotes the specific terminal in use. Various TDF files are supplied with the system software.

If an attempt is made to invoke U/BL with an invalid TDF, warning messages will be displayed and an error 9131 generated. You will not be allowed to continue using U/BL.

Use the STMA 10,99,tdf$ statement if you want to change the current terminal definition file.

This environment variable cannot be changed by a $PUTENV statement.

Example

Under Windows

BBTERM=\USER\UBL\COLOR.TDF

Under UNIX

BBTERM=/user/ubl/d200.tdf

See also

STMA_10


BBTESTANDSET

Description

Setting the BBTESTANDSET environment variable to Y forces ublmon to set up the test and set method of file locking. If set to N, it forces U/BL to use the operating system's semaphores which is a slower method. If not set at all, then the test and set method will be used on the 386/486 UNIX, IBM RS/6000 AIX and AViiON DG/UX platforms only.

With multi-processor DG AViiONs, there is a disadvantage in using test and set and, therefore, BBTESTANDSET should be set to N. Warning, this may apply to other multi-processor systems.

Note: The environment variable BBSEMUNDO will have no effect if the test and set method is being used.

If this environment variable is changed after the Run-Time has been started, then the Run-Time must be Killed and re-Started (using ublmon's K and S options respectively) before the change will take effect. It cannot be changed by a $PUTENV statement.

Example

BBTESTANDSET=Y

See also

BBSEMUNDO


BBTHROW

Description

The BBTHROW environment variable is set to Y to ensure that the printer throws a page every time it is OPENed. The default is N.

This environment variable can be changed by a $PUTENV statement.

Example

BBTHROW=Y


BBTIMEOUT

Description

The BBTIMEOUT environment variable can be used to set the number of seconds that an INPUT statement will wait before generating the error:

9185 - INPUT timed out.

This environment variable can be changed by a $PUTENV statement.

Example

BBTIMEOUT=60

See also

INPUT

TINPUT


BBTMP

Description

The BBTMP environment variable denotes the directory where all temporary files reside. These files include the '.LPT' spool files created when the BBSPOOL environment variable is set and other work files. Typically under UNIX BBTMP is set to the UNIX temporary directory /tmp.

It is recommended that the shared facilities file denoted by the BBSHARE environment variable, if used, resides in the temporary directory.

Note: Under many UNIX operating systems, the contents of /tmp directory are removed when the system is brought up. Also, if BBTMP is set incorrectly, the product will be unable to action a SWAP statement and will generate error 65. This is because the BBTMP directory is used to maintain a swap file that hold information about the previous swap levels.

If an invalid directory or file is used in setting BBTMP, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBTMP contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement, but, as it is used extensively by U/BL, care must be taken that the new setting is appropriate.

Example

Under Windows

BBTMP=\TMPDIR

Under UNIX

BTMP=/tmp

See also

BBSHARE

BBSPOOL


BBTOPICS

Description

The BBTOPICS environment variable specifies the maximum number of topics (!Items) that can appear on any one help index. The defaults are 100 under UNIX and 50 under Windows.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBTOPICS=200

See also

BBHMEM

HELP


BBTRACE

Description

The BBTRACE environment variable is a bit mask which can be used to set various tracing options. It assists developers in following various events in the lifetime of their programs. The bit settings are:

Bit | Value | Option
1 | 1 | Trace all LOPENs
2 | 2 | Trace all SWAP errors
3 | 4 | Trace file OPENs
4 | 8 | Trace $SORT operations
5 | 16 | Trace user defined Help system errors
6 | 32 | Reserved
7 | 64 | Trace all keyboard buffering and mapping
8 | 128 | Trace User Routine Error (Error 37).

The trace output is printed onto the screen as it occurs, and as such may cause the look of screens to be corrupted. `For this reason these facilities should only be used during development.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBTRACE=5

This sets bits 1 and 3, so all LOPENs and OPENs will be traced.


BBTTYEOF

Description

The BBTTYEOF environment variable is used to override the default action on detecting the end of file on the standard input when the standard input is from a terminal. This action is normally to ignore the condition. By setting BBTTYEOF=Y, the product will BYE off on detecting the end of file on the standard input.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBTTYEOF=N

See also

BBEOF


BBTTYNO

Description

A constant SYS(4) value can now be specified by the BBTTYNO environment variable:

BBTTYNO=n

where, n is the value you wish to be returned on this terminal by a SYS(4) statement.

Note: BBTTYNO takes precedence over any BBTTYS settings.

This environment variable cannot be changed by a $PUTENV statement.

Under Windows

If the multi-tasking facility is in use, then the task number will be added to this value for any task other than the first one. For example, if a user is allowed three sessions under the multi-tasker, and the SYS(4) value specified by BBTTYNO is 8, then when the user invokes Basic, SYS(4) will return 8. When the user presses ALT-F2 to bring up the second session, SYS(4) will return 9 (i.e. the BBTTYNO value + 1). Pressing ALT-F3 to bring up the third session will make SYS(4) return 10 (i.e. BBTTYNO + 2). Press ALT-F1 to return to the first task, and SYS(4) will return 8.

If the multi-tasker is being used, it is up to the user to make sure that each workstation on the system has a unique BBTTYNO value that is at least the number of permitted multi-tasker sessions greater than its neighbour. For example, if there are five workstations on the system, and the maximum number of multi-tasker sessions allowed is four, the BBTTYNO values could be as follows:

Workstation | BBTTYNO number | Maximum SYS(4) value (when on multi-task 4)
1 | 1 | 4
2 | 5 | 8
3 | 9 | 12
4 | 13 | 16
5 | 17 | 20

Example

BBTTYNO=4

See also

BBDUPSYS4

BBNXTFREE

BBSYS4INC

BBTTYS


BBTTYPE

Description

The BBTTYPE environment variable has been provided to support the two main terminal types, 6 and 8. It not only sets the terminal type for the STMA 1,0 and STMA 9,0 statements, but provides the non cursor-key editing of a type 6 screen. The default value for BBTTYPE is 8 when the product is running in the foreground, or 6 if it is running as a background task.

These defaults are changed by setting BBTTYPE to 6 or 8. Use the STMA 2,0 statement to change the terminal type.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBTTYPE=6

BBTTYPE=8

See also

BBSEDIT

STMA 2,0


BBTTYS

Description

The BBTTYS environment variable can be changed by a $PUTENV statement, but any change will not affect the SYS(4) values.

This environment variable should be assigned to the name of the file that fixes device names to particular terminal lines. The file, which is ASCII, is in the following format:

For UNIX

Device Name | SYS(4) Value
/dev/tty01 | 1
/dev/tty02 | 2
/dev/tty003 | 3
and so on.

The device name's format is operating system specific. Line characteristics such as baud rate and flow control can be set for the serial devices listed in the BBTTYS file (see below).

Under UNIX, SYS(9) is always the job slot number, while SYS(4) is either the job slot or the BBTTYS value, if set up.

BBTTYS cannot be used to set up a SYS(4) of 0 as this is not allowed, that is, the entry /dev/tty0 0 is illegal. If an attempt is made to use the same SYS(4) value for more than one terminal, the product will not start on any but the first terminal to be brought up with that value (see BBDUPSYS4 for the exception). The following message will be displayed on any terminal attempting to use a SYS(4) value which is already being used by another terminal:

Illegal SYS(4) value of n

This value is in use by another UBL job.

where n is the SYS(4) value.

If the BBTTYS file does not include an entry for the terminal from which you logon to the product, then the following warning message will be displayed when the product is invoked on that terminal:

WARNING: Terminal line (/dev/<line no>) not found in BBTTYS.

and that terminal will be assigned the next available job slot number for its SYS(4) value. This value may not be unique as it may conflict with an entry already made in the BBTTYS file. The BBTTYS file can be used to set line control characteristics such as baud rate, flow control, and so on, when OPENing serial devices such as printers.

Whenever a serial device is OPENed, its name will be looked for in the BBTTYS file, and its characteristics will be set to those specified. For example:

/dev/lp0 8 B9600 IXON IXOFF

sets the SYS(4) value for the printer on line /dev/lp0 to 8, its baud rate to 9600 and enables both start/stop output and input control. The SYS(4) value is not required when OPENing a printer, but it is required for correct syntax. The supported mnemonics are:

Mnemonic | Meaning
B9600 | 9600 baud
B4800 | 4800 baud
B1200 | 1200 baud
B19200 | 19200 baud
IXANY | Any character to restart suspended output
IXON | Enable start/stop output control
IXOFF | Enable start/stop input control
PARENB | Enable parity generation and detection
PARODD | Odd parity - parity will default to even if this is not set
CS8 | Character size is 8 bits
CS7 | Character size is 7 bits
ONLCR | Maps <NL> to <CR-NL> on output
ICANON | Canonical processing is enabled.

Note: All of the mnemonics must be in upper case.

To remove a characteristic, place a "-" in front of its mnemonic. For example:

/dev/lp0 8 B9600 -IXON -IXOFF

To check the line's characteristics from the operating system:

stty -a < /dev/lp0

Improved use of BBTTYS for SYS(4) & SYS(9)

Under Windows single task both SYS(4) and SYS(9) are 1. Under Windows multi-tasking both SYS(4) and SYS(9) are the task number. Under NET single task per node both SYS(4) and SYS(9) are normally given the next job number in the job table. If BBTTYS is set for Novell NetWare, then the SYS(4) value will be the number allocated to the workstation in the BBTTYS file. The SYS(9) value will always be the same value as SYS(4), unless the SYS(4) value is greater than the licensed user count.

Under Novell NetWare with multi-tasking, to provide a unique and constant SYS(4), BBTTYS has been extended to include a task number associated with the network station address. This is achieved by appending '_n' to the network station address (in the BBTTYS file) where n is between 1 and 9. For example, a BBTTYS file may contain:

000002423E9A_1 1

000002423E9A_2 3

00AA0B126F7A_1 2

00AA0B126F7A_2 4

and so on.

Note: | 000002423E9A } | Both have the same meaning.
 | 000002423E9A_1 }

It is important that UNIQUE SYS(4) numbers, in the same range as the number of jobs allowed, are allocated to the first multi-task for each workstation, for example, 1 to 16, if a 16 user licence has been supplied.

Example

Under Windows

BBTTYS=\USER\UBL\TTYFILE

Under UNIX

BBTTYS=/user/ubl/portsfile

See also

BBDUPSYS4

BBEXTRAJOBS

BBSYS4INC

BBTTYNO


BBTTYSLIMIT

Description

The BBTTYS file provides a means of setting the SYS(4) value for a U/BL job based on the client (be it a PC running U/Gi or a dumb-terminal) that is executing it. For U/Gi jobs running in graphical mode, this setting is based on the hostname of the client PC or, for Microsoft Terminal Server, the name under which the user has logged onto Terminal Server. For sessions where U/Gi is not running in graphical mode, or the U/BL job is being run from a dumb-terminal (or other PC-based emulator) this setting is based on the name of the serial or TCP/IP pseudo device over which the session is running.

By default, U/BL employs any SYS(4) mapping for the client that it finds in the BBTTYS file. Otherwise, if no relevant mapping is present, U/BL uses a default value. Using a default value can have disadvantages. For instance, a defaulting job may take a SYS(4) value allocated for use by another client.

To combat these limitations versions of U/BL 2.20 and above use the BBTTYSLIMIT environment variable. Setting BBTTYSLIMIT to Y, limits U/BL to run only on those clients explicitly listed in the BBTTYS file (either via the device name; client PC name or, in the case of Terminal Server, username). U/BL will not start a session if the client is not listed in the BBTTYS file.

In addition to controlling which clients can use U/BL (based on whether or not they are listed in BBTTYS), BBTTYSLIMIT can control the number of U/Gi-based U/BL sessions any given client PC can run. This is achieved via the existing logic where up to five SYS(4) values can be defined for any given client in the BBTTYS file. If a client has exhausted the number of different sessions listed for it in BBTTYS, with BBTTYSLIMIT set (to Y) U/BL prevents an extra session from being started.

Example

BBTTYSLIMIT=Y


BBUBBERM

Description

A file containing product specific error codes and their associated messages is included in the system software. The BBUBBERM environment variable can be set to the full pathname of the UBBERM file so that the product will display meaningful error messages when necessary.

If an invalid directory or file is used in setting BBUBBERM, the following message will be displayed when U/BL is started up (U/BL will start up as normal after displaying the message):

WARNING: BBUBBERM contains invalid directory/file <pathname>

This environment variable can be changed by a $PUTENV statement.

Example

BBUBBERM=C:\USER\UBBERM

See also

BBERM


BBUNIXTEXT

Description

The BBUNIXTEXT environment variable allows you to turn off the default behavior of the Windows version of U/BL that sees a Carriage-Return; New-Line terminator sequence being outputted whenever a single Carriage-Return or New-Line character is requested to be PRINTed to a file.

This new functionality applies to all PRINT FILE statements whenever the output is not directed to channel 16. If such a statement requests that either a Carriage-Return or New-Line character is output to the file, then under the new functionality, U/BL outputs a single New-Line character. This behavior directly mirrors that of the UNIX versions of U/BL in this respect.

For performance reasons, this environment variable is not $PUTENVable.

Example

BBUNIXTEXT=Y


BBUNPEND

Description

Currently, if input is redirected from a text file the product automatically unpends the Licence Banner. However, previous revisions required the text file to contain as the first entry <CR> to unpend the banner. If you have already set up such a text file with <CR> as the first entry then set the BBUNPEND environment variable to Y so that the product will continue to use that entry to unpend the banner.

This environment variable can be changed by a $PUTENV statement, as it is only used to change the operation of the banner.

Example

BBUNPEND=Y

See also

BBAUTOBAN


BBUSER

Description

The BBUSER environment variable defines the user Logon code, for example, OPABC. The default Logon code is, AANONE.

The environment variable can be changed by a $PUTENV statement, but any change will not be reflected in the ublmon report display.

Example

BBUSER=OSABC


BBUSI

Description

The BBUSI environment variable can be used to suppress the null (ASCII 0) terminator on a PRINT USING "Z" statement. Set BBUSI to Y to enable this feature.

BBUSI emulates the B32 "USI" (or "USING_NULL") runtime switch.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBUSI=Y


BBVAL

Description

The BBVAL environment variable controls the action of the VAL statement.

This environment variable resolves a limitation with U/BL's implementation of the VAL statement. Basically there are two different aspects of the VAL statement that are mutually exclusive as far as U/BL is concerned. These conditions are as follows:

Case 1: Use of the error-variable's value within the VAL statement

00010 LET RESULT=VAL(STRING$[ERROR],ERROR)

Case 2: Use of the error variable's value following the VAL statement

00020 LET RESULT=VAL(STRING$,ERROR)*ERROR

Only one of these two conditions can be supported by U/BL at any one time, and the BBVAL allows the user to select which implementation they require. The default action of U/BL, is to support the second case where the error-variable is used following the VAL statement in the expression. To support the former case, BBVAL must be set to 'Y' at the time the program is ENTERed into U/BL.

If a U/BL program is generated with BBVAL=Y then that program will not correctly evaluate any expression where the error-variable appears after the VAL statement. Similarly if BBVAL was not set (or set was to N) at the time the program was ENTERed, then expressions where the error variable is referenced in the VAL statement will be evaluated incorrectly.

This mutual exclusion means that it is impossible for U/BL to support lines of code which originated in other dialects of Business BASIC where the value of the error-variable is referenced in and following the VAL statement in the expression. For example:

00030 LET RESULT=VAL(STRING$[ERROR],ERROR)*ERROR.

Like Data General Business BASIC, U/BL also has difficulty evaluating VAL expressions when the error variable is used earlier in the expression. For example:

00040 LET RESULT=ERROR*VAL(STRING$,ERROR)

This environment variable cannot be changed by a $PUTENV statement.

Example

BBVAL=Y


BBVERBOSE

Description

By either setting the BBVERBOSE environment variable toY or entering $TURN_ON(VERBOSE) at the '*' prompt, U/BL is able to test for:

  • Mis-matched FOR statements

  • FOR without a corresponding NEXT

  • NEXT without a corresponding FOR

  • Block IF found without corresponding END IF

  • END IF found without corresponding block IF

  • DO WHILE/$DO_WHILE found without corresponding END

  • LOOP/$END_DO

  • END LOOP/$END_DO found without corresponding DO

  • WHILE/$DO_WHILE

  • Out of sequence line numbers on an ENTER

  • Long variable names which have not been truncated on being ENTERed.

This environment variable can be changed by a $PUTENV statement.

Example

00010 FOR I=1 TO 10

00020 FOR A=1 TO 20

00030 NEXT B

00040 IF X THEN

00050 DO WHILE X

In this example, U/BL displays a mismatched FOR statement at line 20, an unmatched NEXT at line 30, block IF without corresponding END IF at line 40, a DO WHILE without END LOOP at line 50 and the FOR at line 10 has no NEXT.


BBWINDOWS

Description

The BBWINDOWS environment variable is one of a group used to configure the product. It determines whether windows are required. If set to Y then the default buffer size is available. Otherwise a specific buffer size can be set.

Note: In a multi-user environment, for example, under UNIX or Windows NT, each user can have a differing configuration, however, the product is unlikely to be used in this way.

If this environment variable's setting is changed, then the change must be made before U/BL is invoked.

This environment variable cannot be changed by a $PUTENV statement.

Example

BBWINDOWS=Y

BBWINDOWS=40000


BBWRITECHK

Description

U/BL checks the size of a numeric variable when writing to a string. If the value exceeds the length of the string or the value of the variable exceeds the precision of the variable, then the following error is generated:

ERROR 16 - Arithmetic

This check can be disabled by setting the environment variable BBWRITECHK=N, however, the value placed in the string will be truncated.

This environment variable can be set dynamically using the $PUTENV statement.

Example

A$=CHR$(2^32,4)

This syntax will generate the error described above unless the BBWRITECHK environment variable is set as follows:

BBWRITECHK=N


BBWYSE

Description

Normally, U/BL does not act on an end character attribute sequence if the character attribute hasn't been turned on, for example, it will ignore an @(-41) - stop blinking - if an @(-40) hasn't been issued. Also, because Wyse terminals use an extra cursor position for a character's attributes, U/BL's optimized cursor positioning can cause problems.

Setting the BBWYSE environment variable to Y, will allow an end character attribute sequence to be sent to the terminal even if the attribute is not already on, and will also turn off U/BL's optimized cursor positioning.

This environment variable can be changed by a $PUTENV statement.

Example

BBWYSE=Y


BBYROFFSET

Description

This environment variable is provided to facilitate year 2000 application testing without having to forward date the computer the testing is taking place on. While this does not allow for complete certification of the application, as an aid to initial testing and to enable the scope of the year 2000 issues to be ascertained this setting has tremendous value.

The environment variable is used by setting it to a number of years by which U/BL offsets date information. Whenever U/BL receives the current date from the operating system (including when U/BL interrogates the current date of a file), that date will immediately have the value of BBYROFFSET added to it. The statements for which this applies are:

_CHECK | _FCB | _FCB$ | LISTH
STME 6 | STME 7 | SYS(152) | SYS(2028)

In addition, the internal operation of U/BL (such as banner processing) will also be subject to this year offset. This is so that as much as possible of the application's operation, including U/BL, is tested when using this facility. Obviously, as the operating system's date has not been changed, the compliance of the operating system or how its system calls might affect the operation of U/BL will not be tested when using this environment variable. The only way to test these aspects fully is to run the machine in a forward dated environment.

What this environment variable does not affect is cosmetic issues and date stamps which are not an integral part of the BBASIC language. For instance, the datestamp written on a $D or $P report will show the real date, not the date offset by the value of BBYROFFSET. As this environment variable is merely lying about the current date to BBASIC, it will also not set an offset date on any file created or amended during testing. This prevents problems with files being created on the system with a date in advanced of the system date. Whenever a foreground U/BL job is invoked with this testing environment enabled, to warn the user, U/BL displays a message in a window and requires the user to accept that they are about to run in a test environment which offsets date values by a number of years. To prevent this warning from causing problems when testing redirected U/BL jobs, it is not implemented on background U/BL processes. This environment variable can not be changed by a $PUTENV statement.

Example

BBYROFFSET=4

This ensures offset any year by 4 years, i.e. if the current system date is 1998, U/BL reports it as 2002.


UBLNTBKDROP

Windows NT and Windows 2000 have a process scheduling model that can result in background tasks using up the majority of CPU resources and thus depriving interactive tasks of CPU time. When many users are using U/BL on Windows NT or Windows 2000, this can result in slow performance to interactive users and can cause problems logging in when long reports are being processed.

To combat this U/BL reduces the priority of a U/BL process once a certain number of non-interactive lines have been run, and boosts it back up when awaiting input.

Setting the UBLNTBKDROP environment variable controls the amount by which the process priority is reduced. This can range from 0 to 4. However, values greater than two have no greater effect unless UBLNTPRIORITY environment variable has been set to increase the process priority. That is, there is a limit below which the process priority cannot be decreased. The default value is 1.

Example

UBLNTBKDROP=1


UBLNTBKTHRESHOLD

Description

Windows NT and Windows 2000 have a process scheduling model that can result in background tasks using up the majority of CPU resources and thus depriving interactive tasks of CPU time. When many users are using U/BL on Windows NT or Windows 2000, this can result in slow performance to interactive users and can cause problems logging in when long reports are being processed.

To combat this U/BL reduces the priority of a U/BL process once a certain number of non-interactive lines have been run, and boosts it back up when awaiting input.

Setting the UBLNTBKTHRESHOLD environment variable controls the number of non-interactive lines that must be run before the process priority is dropped. To disable this functionality set the UBLNTBKTHRESHOLD environment variable to -1 . The default value is 1000.

Example

UBLNTBKTHRESHOLD=1000


UBLNTEXE

Description

The UBLNTEXE environment variable specifies the UBL executable to be run. This is to enable progressive version upgrades.

Example

UBLNTEXE=C:\UBL\bin


UBLNTGUI

Description

The UBLNTGUI environment variable controls whether U/BL runs in gui mode or not. Setting this variable to Y allows U/BL to use the graphical objects in U/Gi. Setting this to N disables this and it runs as though through a dumb terminal.

Setting UBLNTGUI to F makes U/BL use U/Gi to determine if users are bringing up multiple jobs by the same user and then allocates free of charge jobs, up to a maximum of 4 (like it normally does for UBLNTGUI=Y). It then continues to run as though UBLNTGUI set to N (dumb terminal mode).

The default setting is Y.

Example

UBLNTGUI=Y


UBLNTHEX

Description

The UBLNTHEX environment variable is used to specify that FILETRANSFER operations send data in hexadecimal rather than binary format. This doubles the number of characters transferred but avoids all conflicts with the telnet protocol.

The default setting is N.

Example

UBLNTHEX=Y


UBLNTLOCKWORKTOP

Description

The UBLNTLOCKWORKTOP environment variable controls the access U/BL is allowed to the desktop of the machine on which U/BL is running. In order to allow users who are not Windows NT Administrators to use U/BL, the U/BL process must lock both the Windows station and the desktop. By default, U/BL locks the 'worktop' of the interactive user (UBLNTLOCKWORKTOP=Y). This has the side effect that any screen-saver running on the NT server will be unable to gain access to the 'worktop' and will fail with an error.

Setting UBLNTLOCKWORKTOP=L changes the operation of U/BL so that instead of locking the 'worktop' of the interactive user, it attempts to create and lock its own, invisible worktop. This allows any screen saver to work correctly but this functionality has been known to exhibit problems under some service pack levels of Windows NT and Windows 2000.

Setting UBLNTLOCKWORKTOP=N prevents U/BL from locking any 'worktop' which allows any screen saver to work. However, this setting restricts the use of U/BL to user accounts, which have Administration privileges. If non-administrator accounts attempt to run U/BL certain operations within U/BL (such as file access to network drives and $EXECUTEs) can cause a 'User 32' message box to be displayed on the system console.

When U/BL is running on Windows NT or Windows 2000, the screen saver on the console of the server machine does not work. This problem can usually be resolved by using the UBLNTLOCKWORKTOP environment variable, but this does not work on all of the older Windows NT service packs. Microsoft outlines an alternative solution to overcoming these errors. Refer to the Microsoft Knowledge Base article, Q142676, Overcoming Usr32.dll Initialization failure errors.

Example

UBLNTLOCKWORKTOP=Y


UBLNTLOG

Description

The UBLNTLOG environment variable specifies a filename to receive U/BL's logging information for debugging purposes. Use of this environment variable allows logging on a per user basis rather than the global switch provided by the U/BL Control Panel. This environment variable must be set either in the global U/BL environment (as set via the U/BL Control Panel) or in a given user's environment (as set by the U/BL Administrator). Any UBLNTLOG setting in the BBENV file is ignored.

Example

UBLNTLOG=C:\ubl\misc


UBLNTLOGFILE

Description

If the UBLNTLOGFILE environment variable is set to Y, U/BL will log its file input/output operations whenever U/BL's logging feature is enabled.

Example

UBLNTLOGFILE=Y


UBLNTNOODBC

Description

U/BL uses some ODBC technology. On a PC where ODBC has become corrupted, this can sometimes produce a warning message when starting U/BL. If this happens, setting UBLNTNOODBC to Y prevents this from occurring by preventing U/BL from attempting to use the ODBC functionality. The default setting for this environment variable is N.

Example

UBLNTNOODBC=Y


UBLNTPRIORITY

Description

The UBLNTPRIORITY and UBLNTSERVERPRIORITY environment variables enable you to lower the priority of reporting processes. This is so that the reports do not use all the CPU time. The UBLNTPRIORITY environment variable sets the priority of a U/BL process. It can be set to the following values:

UBLNTPRIORITY=0 | Normal
UBLNTPRIORITY=1 | Lowest
UBLNTPRIORITY=2 | Lower than normal
UBLNTPRIORITY=3 | Normal
UBLNTPRIORITY=4 | Above normal
UBLNTPRIORITY=5 | Highest

It can be set via a $PUTENV statement during program execution, or on a per-user basis.

Example

UBLNTPRIORITY=4


UBLNTPROG

Description

The UBLNTPROG environment variable specifies the name of the U/BL save file to be run, when starting U/BL.

Example

UBLNTPROG=progmenu


UBLNTSERVERPRIORITY

Description

The UBLNTSERVERPRIORITY and UBLNTPRIORITY environment variables enable you to lower the priority of reporting processes. This is so that the reports do not use all the CPU time. The UBLNTSERVERPRIORITY environment variable also raises the priority of the server program, so it gets more of the available CPU time. It is set as follows:

UBLNTSERVERPRIORITY=x [,y]

The first value x sets the priority of the U/BL Server, using the following values:

0 | Normal
1 | Lowest
2 | Lower than normal
3 | Normal
4 | Above normal
5 | Highest

The second value, if set to 1, raises the priority of the whole server process. This must be used only in conjunction with normal or lower (<=3) x values.

Example

UBLNTSERVERPRIORITY=2,1


UBLNTSHAREDEVS

Description

By default, devices under Windows NT or Windows 2000 are not shareable. Only one copy may be open at once, even in the same process. Setting the UBLNTSHAREDEVS environment variable to Y, allows ports to be shared in the same process. In addition, this allows ports that have been RINGBUF'ed to be used by a child process that specifies the -port flag. For example:

OPEN FILE [1,5],"COM1"

RINGBUF 1,A$ :

fails unless:

UBLNTSHAREDEVS=Y

Example

UBLNTSHAREDEVS=Y


UBLNTSIGNALCHECK

Description

The UBLNTSIGNALCHECK environment variable setting is a number which specifies how often, in tenths of a second, signals are checked during idle time. The default value is 3. Setting this lower makes the signal response faster, but at the expense of CPU utilization. Setting it higher reduces CPU usage but make U/BL less responsive to IKEYs.

Note: This environment variable is not used when running U/BL with a Winsock 2 compliant TCP/IP stack, where U/BL uses a more advanced method of signal checking. As this method results in a dramatic performance improvement, Transoft suggest that a Winsock 2 compliant TCP/IP stack is used wherever possible. The TCP/IP stack supplied with Windows NT or Windows 2000 is such a stack and other, independent versions are available for Windows 95/98.

Example

UBLNTSIGNALCHECK=3


UBLNTVALIDATEMONITOR

Description

If the UBLNTVALIDATEMONITOR environment variable is set to Y (the default), only U/BL Administrators can use the U/BL Monitor utility. If this is set to N, then any user can use the U/BL Monitor utility.

Unlike most of the other UBLNT environment variables, UBLNTVALIDATEMONITOR can only be used as a global variable.

Example

UBLNTVALIDATEMONITOR=Y


ActiveX Controls

An ActiveX control is a component, a chunk of programmable functionality that can be used in many different environments. To keep down their size, ActiveX controls usually do not allow a high level of configurability through a user interface. Instead, they can be configured by setting flags associated with the control.

ActiveX controls can be used within ActiveX containers, which are applications that have been designed to allow the embedding and manipulation of ActiveX controls. Many programming languages and productivity tools, such as Visual Basic, Visual C++, Delphi and Access support the use of ActiveX controls. Controls can be created and embedded into applications and documents, controlled by the setting of variables (or properties, as they are more commonly referred to in this environment) and the calling of functions contained within the controls (commonly known as methods).

In addition, ActiveX controls can signal their containers of asynchronous events which may be generated by the user interacting with the control, for example, clicking a button, or by an external event such as a timer timing out or the arrival of new mail.

Version 4.0 (32-bit) of U/Gi is itself an ActiveX container. Enhancements to the U/BL language present in U/BL 2.20+ allow ActiveX controls to be created within U/Gi and controlled by a U/BL Business Basic program.

This section contains details about the U/Gi 4.0 and U/BL 2.20 extensions which allow ActiveX controls to be embedded and controlled from within U/BL. It must be read in conjunction with the U/BL Windows Object Commands section and the relevant ActiveX tutorials.

Supported ActiveX commands

The following ActiveX commands are currently supported:

  • AXCALL

  • AXCREATE

  • AXSET

  • AXGET

  • AXEVENT

Full details of these commands are provided in the A-Z Statement Guide.

Advanced facilities

The following advanced topics are discussed in the following sections:

  • Optimizing performance

  • Automatic installation of ActiveX Controls on client PCs

  • Licensed controls

  • Property sheets and configuration data.

Tutorials

Several tutorials are provided to give concrete examples of how a variety of commonly used ActiveX controls can be used efficiently and quickly.

See the section ActiveX Control Tutorials.


Optimizing Performance of ActiveX controls

In order to use an ActiveX control it must first be installed and then registered on the client PC. The following steps can be taken to optimize the performance when embedding ActiveX Controls in a U/BL application:

  • Carefully examine the ActiveX control documentation

The most dramatic improvements in performance will come by examining the documentation for the ActiveX control that is being used. Often, there are many ways of achieving the same end, and the most obvious route may not be the most optimal for performance.

  • Setting the BBGUIUSERMODE environment variable

Setting the BBGUIUSERMODE environment variable to Y will disable status code returns from U/BL Windows Object commands that are unlikely to fail unless a programming error has occurred. This significantly improves response times, especially during long sequences of Windows Object commands.

Note: This environment variable should not be set during program development, as programming errors are likely to be missed.

  • Ignoring the return from an AXCALL statement

The AXCALL statement provides a parameter which receives the result of the ActiveX method call. Some methods do not return results, and for some the result is irrelevant. By using either a numeric expression or an empty string for the RETVALUE of the AXCALL statement, U/BL knows that the return is to be ignored and so performance is improved. This optimization is automatically enabled when the BBGUIUSERMODE environment variable is set.

  • Send only the part of a string containing text

Strings have two lengths; their dimensioned length and the length of the valid text contained within that length. U/BL sends the whole dimensioned length unless specifically told not to (as there are certain cases where this is necessary). By sending only the part of the string containing data, performance can be improved. For example:

AXCALL(1,"ADDITEM",A,B,A$[1,LEN(A$)-1])


Licensed Controls

Professionally-marketed ActiveX controls are often licensed so that only one developer may develop with the control. During the installation of the control, a license key file is placed on the development machine, and it is a condition of the licensing that this file is not distributed with the control. In order to use the control on a computer that does not have the license file, a license string must be passed through to the control when it is created using the AXCREATE statement.

This license string can be generated on a licensed machine by using the GETXTRAINF(ID,2) statement against the control as follows:

DIM LIC$[100]

AXCREATE(1,5,5,10,40,"","My.LicensedControl","",1,STAT)

GETXTRAINF(ID,2,LIC$)

PRINT LIC$

This statement should be placed into the program code that creates the ActiveX control. The license string should then be copied into the final program code, as shown below:

DIM A$[100]

REM **** Header to indicate License String ****

A$="LIC:"

REM **** License string ****

A$[0]="0E1A02C894238762ADBC23456432"

AXCREATE(1,5,5,10,40,"","My.LicensedControl",A$,1,STAT)

Note:

Remember to change the ProgID in the AXCREATE statement to that of the control you wish to use.

The 'axman' sample U/BL program provided with U/Gi 4.0 will help automate this task by automatically generating the license string and the AXCREATE statement.

Some controls will not work correctly in design mode even if they are created with a valid license string unless a valid license key file is present on the machine. If this is the case, switch to user mode while using the control using the SETGUIOPT statement as follows:

SETGUIOPT(31,"1")


Automatic installation of ActiveX Controls on client PCs

The following extensions improve the ease with which ActiveX controls and other custom files can be installed.

FileTransfer predefined directory macros

You can use the following mnemonics at the start of the client (U/Gi) filename parameter in the FILETRANSFER statement to indicate predetermined directories on the client PC. This allows installation of files in well-defined directories on PCs with different directory structures.

$(WINDIR)

The Windows directory on the client

$(WINSYSDIR)

The Windows System directory:

  • system subdirectory of the Windows directory on Windows 95 or Windows 98

  • system32 subdirectory of the Windows directory under Windows NT

$(TMPDIR)

The temporary directory

$(TEMPDIR)

Alias for above

For example:

00010 REM **** FTMACROS ****

00100 DIM A$[100]

00110 OPEN FILE[0,0],"FTM.TST"

00120 PRINT FILE[0],"Hello"

00130 CLOSE

00140 FILETRANSFER "FTM.TST","$(WINDIR)\FTM1.TST",0,STAT

00150 FILETRANSFER "FTM.TST","$(WINSYSDIR)\FTM2.TST",0,STAT

00160 FILETRANSFER "FTM.TST","$(TMPDIR)\FTM3.TST",1,STAT

Self registration of ActiveX Controls

Before an ActiveX control can be used on a PC it must first be registered so that the system is aware of its presence. The FILETRANSFER statement has been enhanced to optionally perform this registration when transferring ActiveX controls onto a PC. To do this, invoke the FILETRANSFER statement using mode 64. In conjunction with mode 8 (REFRESH), this can ensure that the latest copy of ActiveX controls are installed on client PCs without user intervention.

A status of 22 is returned if the registration failed, or if self registration is attempted on files that are not '.OCX' files or DLLs.

Note: Some older ActiveX controls cannot be self-registered.

010 REM **** Test DLL server registration ****

020 FILETRANSFER("\tmp\TSTab.ocx","$(WINSYSDIR)\TSTab.ocx",2,STAT)

030 PRINT STAT


Property Sheets and Configuration Data

Many ActiveX controls can present a user interface to allow program designers to configure the control. This is usually in the form of a series of property sheets that control how the control works. These property sheets can be displayed by calling SETXTRAINF(ID,1,"") on the control.

After the control has been configured in this manner, its state can be retrieved from a control, stored into a string and re-used when the control is created to restore the state immediately. The state is retrieved by using the GETXTRAINF(ID,1) call, and the resulting string is passed into the AXCREATE statement. For example:

REM * Create control, show property sheets and store data *

DIM Z$[10000]

AXCREATE(1,5,5,10,40,"","MSCAL.Calendar","",1,STAT)

REM * Show the properties *

SETXTRAINF(1,1,"")

INPUT A

REM * Get the configuration data *

GETXTRAINF(1,1,Z$)

PRINT Z$

REM * Recreate the control as it was stored *

DIM Z$[10000]

REM * Tag to indicate the following is data *

Z$="DATA:"

REM * Replace this with the data from the GETXTRAINF call *

Z$[0]="A01234CD516829399432491020EDBA2321732173392392199"

Z$[0]="BACD516829399432491020EDBA2321732173392392199"

AXCREATE(1,5,5,10,40,"","MSCAL.Calendar",Z$,1,STAT)

If there is a significant amount of data, it may be preferable to store it in a file rather than in program code. If the control is both licensed and has configuration data, the string passed to the AXCREATE statement should be of the form:

"LIC:<license string>:DATA:<configuration data>"

The DATA text should be separated from the end of the license text with a colon.

Note: The 'axman' sample U/BL program provided with U/Gi 4.0 will help automate this task by allowing the setting of properties, automatically generating the license string, configuration data and AXCREATE statement.


SQL Access Commands

This section describes the SQL Access command extensions of U/BL. These allow access to a number of data sources, including legacy systems and RDBMS using ODBC interface technology.

The SQL Access commands can be embedded and controlled from within a U/BL program.

Note: For Transoft specific data sources, these statements only work within a U/SQL Client-Server environment and you must install U/SQL Client-Server onto your server in order to provide access to these file systems.

When using Transoft specific data sources Transoft recommend you use this document in conjunction with the U/SQL documentation.

What is SQL Access?

SQL Access is an interface layer fully integrated with the ODBC driver, which translates simplified SQL statements into the necessary ODBC calls. In order to use this access layer a number of commands are provided that allow U/BL programs to connect to specific data sources. You can then SELECT, UPDATE, INSERT or DELETE data using standard SQL statements. The statements provided are very powerful and allow you to utilise the full functionality of the relational database. Data sources can be either U/BL data sources mapped via a UDD or any other data source for which an appropriate driver has been developed.

SQL Access statements can be embedded into a U/BL Business Basic program to either replace the existing access method, for example, KFIND or READ, or used to extract and manipulate data from other sources. If the data source is U/BL, then in order for these statements to work, the U/SQL Client-Server product must have been loaded onto the server machine where the database is located. In the case of a third-party database, for example, Microsoft Access or Oracle, the appropriate ODBC data source drivers must be present.

Supported SQL Access Statements

The following SQL Access commands are supported:

LOGON

SQLERR

LOGOFF

SQL

EXEC

FETCH

DELCUR

COMMIT

ROLLBACK

Full details of these statements are provided in the A-Z Statement Guide.

Tutorial

A tutorial is provided to give an example of how the SQL Access statements can be used efficiently and quickly.

SQL Access demonstration program

Rem SQL Access Demo
Rem Selects all the orders and order lines for all customers
gosub @dim_variables
gosub @logon_datasource

Rem Main loop
infmt$=""
outfmt$="A30,N4.0,N4.0,N2.0,N4.0,A30,N4.0"
sql$[0] = " SELECT CUST_NAME, ORDERS.ORDNO,ODATE,LINENO,OLINE.QTY,STOCK_TITLE,PRICE"
sql$[0] = " FROM CUSTOMER,ORDERS,OLINE,STOCK"
sql$[0] = " WHERE CUSTOMER.CUSTCODE = ORDERS.CUSTCODE AND ORDERS.ORDNO = OLINE.ORDNO AND OLINE.STKNUM = STOCK.STKNUM "
sql$[0] = " ORDER BY CUST_NAME ASC"
_SQL ("cust_orders",sql$,outfmt$,infmt$,stat)

if stat <>0 then gosub @general_error
_EXEC ("cust_orders","",stat)

if stat <>0 then gosub @general_error
stat=0
do while stat=0

  _FETCH ("cust_orders", outbuf$,stat)

  if stat = 0 then

  gosub @unpack_rec

  gosub @display_rec

  end if

loop
end

@dim_variables
dim dsn$[20],outfmt$[100],infmt$[100],outbuf$[512]
dim sql$[512],cust_name$[30],stock_title$[30]

return

@logon_datasource
input "Enter data source name (e.g. booksw32.udd) ",dsn$
_logon (dsn$,"","",stat)
if stat <>0 then gosub @general_error

return

@unpack_rec

unpack "A30ELCEA30L",outbuf$,cust_name$,order_no,order_date,line_no,qty,stock_title$,price

return

@display_rec

print cust_name$, order_no, order_date, line_no, qty, stock_title$,price

return

@general_error

stop

return


Windows Object Commands

This section describes the Windows object commands for U/BL. These objects allow you to convert your legacy character based applications into modern GUI applications using real Windows controls with the minimum of work, whilst retaining the tried-and-tested business logic of your code.

Note: To use Windows Object Commands, U/BL must be running within U/Gi and in GUI mode (with '-g' switch on UNIX). See Detecting U/Gi from a script.

The Windows object commands provide support for the following features:

  • Background bitmaps

  • Buttons

  • Check boxes

  • Combo boxes and drop-down combo boxes

  • Edit boxes

  • Group boxes

  • List boxes and dropdown lists

  • Menus

  • Message boxes

  • Proportional fonts

  • Radio buttons

  • Silent file transfer

The following sections discuss:

  • Porting Legacy applications

  • Optimizing Windows Object Commands

  • Creating 3D Look Windows

  • The Windows Object Commands

Note: The screen display bitmaps contained in this help file were created under Windows NT 4 or Windows 95/98. Their appearance may be different under other revisions of the operating system software, for instance under Windows NT 3.51.


Porting legacy applications to a GUI environment

The main difference between modern GUI-based applications and traditional character-based applications is not in their appearance, but in the fact that GUI-based applications are event-driven. This means that you are not forced to do everything in a pre-set order, but instead are given the opportunity to develop your own work patterns.

Transoft provides pseudo-event driven programming to enable the conversion of modal character based applications to partially event-driven, GUI-ized ones. The Windows objects return predefined character sequences into the input stream when events are triggered, which can be decoded easily by your input logic and mapped onto existing code.

Transoft recommends taking the following steps when porting your existing applications:

  1. Add shared procedures if you are not already using them. Shared procedures enable all of your programs to share the same core routines. When you change the shared procedure code, the changes are reflected in all your programs.

  2. Get some instant feedback by using U/Gi's status bar and Windows message boxes to provide information and ask the user questions. This is achieved by using the STATUSMESSAGE and MESSAGEBOX commands.

  3. Set up a background bitmap with your logo or your customers logo using SETGUIOPT. Rather than installing it personally on every client machine, use FILETRANSFER, and only update it if the data in the source file has changed.

  4. Add buttons (using the BUTTON statement) to replace or supplement function keys or for other often used functions.

  5. Rather than printing your fields, create Windows edit boxes using the EDITBOX statement. SETTEXT into them when you display data, and GETTEXT rather than inputting from them.

  6. Replace the edit boxes with more advanced controls where appropriate, for example, check boxes for YES/NO checks or dropdown lists for selections.

  7. Use FILEBROWSE to enable the user to save reports on the local PC. Transfer them with FILETRANSFER.

  8. Replace the U/Gi menus with your own by using ADDMENU.


Optimizing Windows Object Commands

Windows objects allow you to modify your existing Business Basic code. They can also reduce the load on the remote server and so boost performance. However, if you are running over a slow network, delays may be introduced which can cause lower user responsiveness. Under these circumstances the following steps can be taken to improve performance:

  • Using the BBGUIUSERMODE environment variable

Setting the BBGUIUSERMODE environment variable allows Windows objects to be optimized for end-user deployment. As there are many Windows object commands which are unlikely to fail at runtime (rather than in a development environment where programming errors can intervene), this switch has been provided to tailor the operation of the object statements for end-user deployment. If BBGUIUSERMODE is set to 'Y' (the default is no 'N'), those objects which only return information under error conditions are modified so they do not send a response back to U/BL. This prevents U/BL from having to wait for the response from U/Gi, and so can dramatically improve performance.

Note: As setting BBGUIUSERMODE=Y prevents most Windows objects from sending back an error return, do not set this switch while you are developing GUI applications, as you may be unable to detect errors in your code.

If you wish to check that there are no errors occurring while running in this mode, a function of the GETGUIOPT statement has been provided to return a count of the Windows object errors since the last check was made.

  • Give the user freedom

Legacy character-based applications often validate each field as soon as it is entered. Windows programs usually allow a large number of fields to be changed at any time, and then an Update or Apply button to be pressed where all the data is validated. This also has the beneficial effect of decreasing the network traffic.

  • Bunch objects which return information together

Bunching together Windows objects that return status information back to U/BL does not produce a performance bottleneck, it is actually beneficial. It does not produce an area of code subject to a delay (as all the objects are configured and return their information back to U/BL), it actually improves performance. This is because the major delay is while the return is being formulated. By grouping all these delays together, you can improve the latency of the program, resulting in a performance improvement.

  • Only transfer files if you have to

Files should only be transferred if necessary. Use the option that checks the date of an existing file to see if it needs to be transferred.

  • Think about your code

Do you really need to fill a large combo box or list box immediately on startup? Or can you wait until the user has made some choices which will reduce the size of the data to be transferred?


Creating 3D-Look Windows

Creating 3D-Look Windows Objects

U/Gi supports the creation of 3D-look Windows objects by using the SETGUIOPT statement. The 3D effect is a visual trick that relies on using a certain set of colors. If you do not use the default colors, the results may be incoherent. If this happens, the only option is to utilize a different color scheme.

To turn on 3D Look, issue a SETGUIOPT (10,"ON"). This will change the color of the background to a gray (192, 192, 192 in RGB) to make 3D controls appear correctly. You should also change the colors of any attributes you use to display text on the back-panel. Note that if you issue a SETGUIOPT (10,"OFF"), the colors will not be restored. You must do this manually.

There are some new SETGUIOPT commands to aid in this:

  • SETGUIOPT (17) - Map a text attribute to a particular foreground color, background color and font style

  • SETGUIOPT (18) - Change colors


The Windows Object Commands

General commands

DDEMESSAGE

FILEBROWSE

FILETRANSFER

GETCOLOR

GETGUIOPT

MESSAGEBOX

SETCOLOR

SETGUIOPT

SETHELP

STATUSMESSAGE

Windows object creation

BUTTON

COMBOBOX

EDITBOX

LISTBOX

RADIOBUTTON

TEXTBOX

Windows object manipulators

ADDITEM

DELETEWO

DELITEM

ENABLEWO

GETNUMBER

GETTEXT

GETXTRAINF

SETFOCUS

SETNUMBER

SETTEXT

SETXTRAINF

SHOWWO

Menus

ADDMENU

Hotspots

CLEARHOTSPOTS

HOTSPOT


Library version of U/BL 5.xx

This topic covers the use of the library version of U/BL 5.xx. It explains how to modify the makefile to include the user package and how to re-link the U/BL executable.

The library version of U/BL 5.xx contains the following files:

*.a | U/BL archive files, that is, glib.a, rlib.a , and so on.
*.h *.fp | Header and function prototype files used in compiling usersubs.c
usersubs.c | Package initialization entry points.
makefile | Program maintainer
ucall_pkg.c | A Skeleton package for adding UCALL statements
fp_pkg.c | An example 'C' package to perform floating point arithmetic. Note: This package is already linked into U/BL and its '.a' files.
mortgage.bb | Example BBASIC program using 'C' routines defined in 'fp_pkg.c'. This can be directly ENTERed and RUN.
usrpkg.doc | Documentation on writing user packages for U/BL
relnote.doc | The release notice.

Re-linking procedure

  1. Add the names of any new object modules to the makefile, appending them to the line beginning 'USER_PARTS='. If the C source files are placed in the library directory, issuing the make command will automatically compile the files into the corresponding object modules.

Refer to the relevant sections of the UNIX Programmers Reference or Guide for full details on using the make utility and writing a makefile.

  2. Ensure an initialization function has been added to the 'userpkg' structure in the 'usersubs.c' module (see 'usrpkg.doc' for full details on how to do this).

  3. Issue the UNIX command make in the UNIX shell, in the library directory. This will link and create a new version of U/BL in the library directory.

  4. Replace the 'ubl' file in the release directory with the newly created version, which includes the user-package.


User C Routines

User Callable C Routines

This facility enables user's own 'C' routines to be incorporated into U/BL and to be called from the user's U/BL programs. The user can name each callable facility with a unique name and incorporate statements of the form:

_PROCNAME (ARG1, ARG2, ...)

into the U/BL programs.

For organizational purposes it is recommended that you group a collection of user routines together as a 'package', for example, an electronic mail interface package may consist of 10 separately callable routines each of which has a different number and type of arguments.

In order for the user's procedures to be recognized and actioned by U/BL they must be linked with the U/BL kernel library. Each user package has:

  • A name

  • An initialization routine

  • A number of named sub-functions

  • A run-time entry point.

For each package to be linked in, the user must:

  • Edit the file usersubs.c and insert the packages initialization routine address in the table of all such addresses.

  • Edit the makefile to include the users object module(s).

When U/BL starts, the package initialization routine is called.

The package initialization routine must call the service routine USRinit (...) to make U/BL aware of the package functions provided.

External Names used by U/BL

When user written 'C' routines are linked into U/BL the possibility of external name conflict occurs.

U/BL external names almost always begin with a lower case 'u' followed by an upper case letter, or begin with an upper case 'U'.

If link errors occur the user will have to change some of their external names.


Service Routines

When calling these service routines, it is recommended you #include "uCALLnew.fp" as this will provide ANSI C style function prototypes or K&R style prototypes. Add -DCPROTO if you want the ANSI C prototypes. If one of the following functions is called with the incorrect number or type of parameters when CPROTO is defined then the compiler will notify the programer. Do not define CPROTO if the C code being developed is not in ANSI C as the compiler may complain.

uCALLnew.fp has prototypes for other functions, which happen to be in the same C module as the ones provided. You must not attempt to use these undocumented functions.

The following functions are supported:

int USRinit (package, entry, nfunc, functions)

int USRinit (package, entry, nfunc, functions)

char *package;

int (*entry)();

int nfunc;

char *functions[];

This function MUST be called during the initialization call to the package. It is used to declare the procedures contained within the package. The function returns 0 if successful and -1 for an error.

Example

static char *functions[] = {

"MYFUNC1",

"MYFUNC2",

"ETC"

};

int mypackage ();

if (USRinit ("MYCODE", mypackage, 3, functions) {

fprintf (stderr, "Init error\n");

exit (1);

}

The area of storage containing the function names must remain constant, that is, must not be overwritten or be an automatic (stack based) variable.

int USRfunction ()

This function returns the function number of the routine being called based upon the position in the table of function names given at initialization ( from 0 to nfunc - 1).

int USRnarg ()

This function returns the number of arguments given in the user function call.

For example, if a user call was:

_MYFUNC (A$, "ABC", X+1)

USRnarg () would return 3.

Note: There is currently a limit of 20 arguments to any user procedure.

int USRatype (arg)

int USRatype (arg)

int arg;

This function returns a value indicating the type of argument arg. If arg is less than 1 or greater than the number of arguments supplied, a run-time error is generated.

The types returned are:

1 - Numeric Variable

2 - Numeric array reference (1 dimension)

3 - Numeric array reference (2 dimensions)

4 - Numeric Expression

5 - String literal

6 - simple String Variable

7 - sub_string expression

int USRalen (arg)

int USRalen (arg)

int arg;

This function returns the length of arguments that are string variables sub-strings or string literals (other types cause a run-time error). By default all string variables are initially considered to be 'input' variables, that is, the length returned is the current length.

char *USRaddr (arg)

char *USRaddr (arg)

int arg;

This function returns the address of the first byte of the string type argument arg. Other types cause a run-time error.

void USRsout (arg)

void USRsout (arg)

int arg;

This procedure converts a string variable or sub-string argument into an 'output' type. This will cause USRalen (arg) to return the maximum length of the string.

void USRsfix (arg, n)

void USRsfix (arg, n)

int arg, n;

This procedure updates the current length of the string variable argument arg (other types cause a run-time error) to 'n'.

long USRnget (arg)

long USRnget (arg)

int arg;

This function returns the numeric value of argument arg (must not be a string type).

void USRnput (arg, val)

void USRnput (arg, val)

int arg;

long val;

This procedure updates the numeric value of argument arg to val (it must be a numeric variable or array reference).

void USRerror ()

This procedure terminates the call with a run-time error. A method of trapping user errors and exceptions of specific types is to include a numeric variable in the call syntax and to return status / error information through that.

void USRrtn ( )

This procedure returns control to the user's U/BL program.


Stages required to add new statements/UCALL's to U/BL

  1. Determine a suitable package name such as 'EMAIL' for an electronic mailing system. This will be the first argument to the USRinit function:

USRinit ("EMAIL" , , , );

  2. Provide a dispatching routine, which will call the individual services that the package provides, for example:

#define SENDMAIL 0

#define RECVMAIL 1

void EMAIL_PKG ( ) /* dispatching function */

{

int type;

type = USRfunction ();

switch (type) {

default: USRerror (); break;

case SENDMAIL xSENDmail (); break

case RECMAIL xRECmail (); break

}

}

This will be the second argument to the USRinit function:

USRinit ("EMAIL" , EMAIL_PKG , , );

  3. Determine the names of the new services this package will provide. These names will be the new statements that can be used within U/BL;

static char * email_funcs[] = {

"SENDMAIL","RECVMAIL",VIEWMAIL"

};

#define NFUNC sizeof (email_funcs) /sizeof (char *)

In U/BL:

10 _SENDMAIL (arg1,..., argn)

This provides the final two arguments to the USRinit function:

USRinit ("EMAIL" , EMAIL_PKG, NFUNC, email_funcs);

  4. Provide an initialization function, which calls USRinit:

EMAIL_init ( )

{

void EMAIL_PKG ();

if (USRinit ("EMAIL, EMAIL_PKG, NFUNC, email_funcs)) {

fprintf (stderr, "Error in EMAIL initialisation");

exit (1);

}

}

This function is then added to the list of user packages in usersubs.c:

void uETIinit ();

.

.

void EMAILinit ();

struct userpkg {

void (*init_proc)();

} uUSRpkgs[] = {

uETIinit,

.

.

uEMAILinit,

.

.

0

};

  5. Develop the 'C' code to perform the required services:

xSENDmail ( )

{

.

.

}

.

.

  6. Rebuild U/BL having first tailored the make/link file(s) to recognize your new C-modules.

Full details on how to do this can be found in the release notice, relnote.doc, included with this software.


External Action Keys

Introduction

The library version of U/BL includes a facility in the user function module, usersubs.c, which allows certain key presses to cause user defined functions to be invoked based on the configuration of the Terminal Definition File (TDF). These key definitions are called External Action Keys.

External Action Keys work in a very similar way to $HOT keys, except that no special support is required from within a Basic program, and a user supplied C function is invoked rather than a Basic routine.

The current state of the program, screen, character attributes, and so on, are stored and restored, so that once the external action has completed the Basic program continues without disturbing screen layout and attributes. An external action key may be invoked from any Basic INPUT statement.

This facility provides a simple access point for C programmers who need to allow Basic to suspend and an external action to be carried out, returning without disruption.

Adding External Functions in 'usersubs.c'

This module allows the user to add C functions and language statements to Basic. There are three new functions provided that offer support for External Action Keys.

These functions provide:

{SYMBOL 183 \f "Symbol" \s 10 \h} | Facility to invoke a function the first time used
{SYMBOL 183 \f "Symbol" \s 10 \h} | Discrete mapping of up to ten user defined keys
{SYMBOL 183 \f "Symbol" \s 10 \h} | Function call made just prior to Basic exiting.

The control functions in usersubs.c are:

void _uExternInit()

This function is called the first time an external action key is pressed. Initialization code should be added to this function.

void _uExternExit()

This function is called immediately prior to Basic termination. Code to uncouple a program from and external system should be placed here.

void _uExternAct()

This function is called each time one of the configured keys is detected. The keys configured in the TDF can be given a range of values from E0 to E9. Once the action function called the key value passed to this function will be in the range 0-9.

Customising External Action Key Functions

This involves adding your own functions to the usersubs.c module, and inserting calls to these functions into the three external action functions provided. In the case of _uExternInit() and _uExternExit() simply add the required code directly to the skeletons, of make functions calls as required.

In the _uExternAct() function modify the case statement to suit your own purposes. The skeleton for this function is as follows:

void _uExternAct ( KeyNum )

int KeyNum;

/* Function to invoke to External Actions - directly called by */

/* External Action Keys as defined in TDF.                     */

{

                if( !ExternalRun )

                _uExternInit( );

/* Add external action code to the case statement */

                switch( KeyNum )

                {

                case 0 :

                case 1 :

                case 2 :

                case 3 :

                case 4 :

                case 5 :

                case 6 :

                case 7 :

                case 8 :

                case 9 :

                default:

                                putchar( '\n' );

                                printf("Key Number = %d\n",KeyNum);

                                system( "ksh" );  /* default action */

        }

       return;

}

Note: All the cases currently lead to the same action, that is, the 'ksh' is invoked. If you wish to give a key a special meaning then all that is required is to write a C function that carries out the external action and insert a call to it in the case statement, followed by a 'break'.

The initialization code is called by virtue or the initialization flag in this function. This is a simple method of ensuring that the initialization code is only called once, and only if the external action facility is actually used. If you decide to change this then be sure that any required special initialization is still performed.

Once the changes have been made 'make' the new customised version of Basic.

Activating the External Action Keys from the TDF

Finally to enable the facility under Basic you need to set the required keys up in your TDF. As with $HOT keys you detail the mapping of the key code sequence to a Basic key value.

An example extract from a TDF is as follows :

rem *********** External Function keys ************

kbf_ext0=1b,5b,32,7e           : HOME key

kbt_ext0=e0

kbf_ext1=1b,5b,31,37,7e      : f1

kbt_ext1=e1

kbf_ext1=1b,5b,31,38,7e      : f2

kbt_ext1=e2

kbf_ext1=1b,5b,31,39,7e      : f3

kbt_ext1=e3

kbf_ext1=1b,5b,32,30,7e      : f4

kbt_ext1=e4

kbf_ext1=1b,5b,32,31,7e      : f5

kbt_ext1=e5

kbf_ext1=1b,5b,32,33,7e      : f6

kbt_ext1=e6

kbf_ext1=1b,5b,32,34,7e      : f7

kbt_ext1=e7

kbf_ext1=1b,5b,32,35,7e      : f8

kbt_ext1=e8

kbf_ext1=1b,5b,32,36,7e      : f9

kbt_ext1=e9

This causes that the 'home' key and the function keys 'f1' - 'f9' under a vt220 emulator to invoke external action function.


U/BL Socket Commands

Sockets are a mechanism for providing inter-process communication, and allow you to communicate with other processes either on the same or a remote machine.

Revisions of U/BL 2.20 and above provide support for several new socket commands, which use TCP/IP sockets. For more information on TCP/IP sockets consult your systems administrator.

Restrictions

  • Up to 20 different sockets may be used from a U/BL session. The socket values start from zero, therefore the maximum socket value allowed is 19.

  • There is no command available to allow sockets to be transferred between different U/BL processes. This may be necessary in the future, but is complex under Windows operating systems.

  • Blocking socket commands (especially SOCKWAIT) do not return immediately from an IKEY statement.

Supported commands

The following U/BL socket commands are supported:

SOCKCONN | Creates a socket and attempts to connect to a remote server
SOCKSEND | Sends data down a previously created socket
SOCKRECV | Receives data from a previously created socket
SOCKWAIT | Waits until a socket or set of sockets are ready for reading
SOCKCLOSE | Closes a socket, or closes all open sockets
SOCKFREE | Returns a valid unused socket number
SOCKSERV | Creates a server socket that listens on a port
SOCKACCEPT | Accepts an incoming connection on a server socket, and creates a new client socket to communicate with it

For a detailed description of the above commands see the A to Z Statement Guide.

Error codes

For the U/BL socket error codes, see Appendix E.


.(period)

.(period) ------------- Action the contents of the dot editor buffer into the BB program

Type

U/BL dot editor command

Syntax

.

Description

The dot editor commands provide a primitive editing capability at the U/BL '*' prompt. When a line is ENTERed from the keyboard, or a program line is LISTed, the last line displayed is left in the edit buffer. The dot editor commands can be used to alter and display this line.

They are primarily designed for use where the terminal type is 8 (see BBTTYPE). The line editor functionality of the STME 27 statement is not available.

Note: Dot editor commands do not work on lines without line numbers or on lines which are followed by lines without line numbers.

The dot commands are:

. | Action the contents of the dot editor buffer into the BB program
.A | Appends text to the contents of the dot editor buffer
.C | Changes and replaces the current line
.E | Edits but doesn't ENTER the current line
.I | Replaces the text in the dot editor buffer
.M | Modify the currently LISTed line
.N | Add a line after the currently LISTed line
.NA | Insert a line after the currently LISTed line
.NB | Insert a line before the currently LISTed line
.P | Displays the current line

See also

.A | .C | .E
.I | .M | .N
.NA | .NB | .P

Appendix J - U/BL Line Editing Commands


.A

.A ---------- Append to the dot editor buffer

Type

U/BL dot editor command

Syntax

.A text

Arguments

text

The text to be appended to the line.

Description

Like all dot commands, .A works on the current line. It pastes text onto the end of the current line. The line is not ENTERed into the program.

Use LIST <line number> if the line to be extended is not the current line. Use .P to display the current line. The .A command must be followed by a character, for example, a space to delimit it. Use the '.' command to ENTER the line into the program, once it has been modified by the .A command.

Example

* list 20

00020 LET I=1 \ J=2

* .a.\ k=3

00020 LET I=1 \ J=2 \ K=3

* .

% Line 20 being overwritten.

* list 20

00020 LET I=1 \ J=2 \ K=3

Note: The "% Line nnnnn being overwritten." message will only appear if the BBOVERWRITE environment variable is set to Y.

See also

. | .C | .E
.I | .M | .N
.NA | .NB | .P

Appendix J - U/BL Line Editing Commands


.C

.C ---------- Change the contents of the dot editor buffer and action the line

Type

U/BL dot editor command

Syntax

.C old new[ /G]

Arguments

old | Text which exists in the current line
new | Text to replace the original
/G | This is an optional switch which causes all occurrences of the original text to be replaced by the substitute text. In line with Data General's implementation of the .C command, U/BL accepts any non null character after the last delimiter and not just /G. If this switch is not set, only the first occurrence is changed.

Description

The .C command changes contents of the dot editor buffer and actions the line. The line is altered so that the original text in the line specified in the old parameter is replaced by new text which is specified in the new parameter. If the first argument doesn't match any text in the line, the line is ENTERed unchanged. The original and substitute arguments old and new can be of different lengths. The first character after .C is used as a delimiter. To change text which contains the delimiter, use a different delimiter, for example, '/'. The .C command works on the whole line, including the line number. It can therefore be used to duplicate lines.

Invoking the .C command is identical to using the .E command (with the same arguments) followed by a '.' command.

Examples

1. Correct a misspelling.

* list 10

* 00010 PRINT "Heelo"

* .c.el.ll

% Line 10 being overwritten.

* list 10

* 00010 PRINT "Hello"

* run

Hello

Note: The "% Line nnnnn being overwritten." message will only appear if the line is numbered and the environment variable BBOVERWRITE is set to Y.

2. Duplicate a line.

* list

00010 PRINT "Hello"

* .c.1.2

* list

00010 PRINT "Hello"

00020 PRINT "Hello"

3. Change first one, then multiple occurrences. Note that any non null character after the last delimiter will have the same effect as /G.

* list 10

00010 PRINT "Peter Piper picked a peck of pickled peppers"

* .c.p.f

00010 PRINT "Peter Pifer picked a peck of pickled peppers"

% Line 10 being overwritten.

* list 10

00010 PRINT "Peter Pifer picked a peck of pickled peppers"

* .c.p.f./G

00010 PRINT "Peter Pifer ficked a feck of fickled feffers"

% Line 10 being overwritten.

* list 10

00010 PRINT "Peter Pifer ficked a feck of fickled feffers"

Note: The "% Line nnnnn being overwritten." message will only appear if the line is numbered and the environment variable BBOVERWRITE is set to Y.

4. Change a full stop.

* list 20

00020 PRINT "as above. the only way to do this would"

* .c/./,

00020 PRINT "as above, the only way to do this would"

% Line 20 being overwritten.

* list 20

00020 PRINT "as above, the only way to do this would"

Note: The "% Line nnnnn being overwritten." message will only appear if the line is numbered and the environment variable BBOVERWRITE is set to Y.

See also

. | .A | .E
.I | .M | .N
.NA | .NB | .P

Appendix J - U/BL Line Editing Commands


.E

.E ---------- Change the contents of the dot editor buffer

Type

U/BL dot editor command

Syntax

.E old new[./G]

Arguments

old | Text which exists in the current line
new | Text to replace the original
/G | This is an optional switch which causes all occurrences of the original text to be replaced by the substitute text. In line with Data General's implementation of the .C command, U/BL accepts any non null character after the last delimiter and not just /G. If this switch is not set, only the first occurrence is changed.

Description

The .E command changes contents of the dot editor buffer, substituting the original text specified on the old parameter with new text specified in the new parameter. The .E command does not action the line after the substitution. If the first argument doesn't match any text in the line, nothing is changed. The original and substitute arguments old and new can be of different lengths. Use .E in exactly the same way as .C, but once edits of the line are completed, use the '.' command to action the line. The first character after .E is used as a delimiter. To change text which contains the delimiter, use a different delimiter, for example, '/'. The .E command works on the whole line, including the line number. It can, therefore, be used to duplicate lines.

The .C command works in the same way as the .E command but it additionally actions the line.

Examples

1. Correct a misspelling

* list 10

00010 PRINT "Heelo"

* .e.el.ll

00010 PRINT "Hello"

* .

00010 PRINT "Hello"

% Line 10 being overwritten.

Note: The "% Line nnnnn being overwritten." message will only appear if the line is numbered and the environment variable BBOVERWRITE is set to Y.

2. Change a line without ENTERing it.

* list 10

00010 PRINT "Heelo"

* .e.el.ll

00010 PRINT "Hello"

* list

00010 PRINT "Heelo"

See also

. | .A | .C
.I | .M | .N
.NA | .NB | .P

Appendix J - U/BL Line Editing Commands


.I

.I ---------- Replace the contents of the dot editor buffer

Type

U/BL dot editor command

Syntax

.I text

Arguments

text

The replacement line

Description

The .I command replaces the contents of the dot editor buffer, with the new text. Use the .I command to type a current line. Use the '.' command after the .I command if the line is to be actioned. For the majority of cases, to replace a line, simply type a new line with the same line number.

Example

* 10 a=1/b=2

* .i 10 a=1 \ b=2

* .

10 a=1 \ b=2

% Line 10 being overwritten.

* list

00010 LET A=1 \ B=2

Note: The "% Line nnnnn being overwritten." message will only appear if the line is numbered and the BBOVERWRITE environment variable is set to Y.

See also

. | .A | .C
.E | .M | .N
.NA | .NB | .P

Appendix J - U/BL Line Editing Commands


.M

.M ---------- Modify the contents of the dot editor buffer

Type

U/BL dot editor command

Syntax

.M

Description

The .M command allows the modification of program lines that do not have program line numbers without having to use an external editor.

The action of the .M command is very similar to pressing CTRL-A, in that the last LISTed line is placed in the edit buffer and the cursor is positioned at the end of the line. The line can now be edited using the left and right arrow keys, CTRL-E, CTRL-A, and so on. Unlike pressing CTRL-A, however, the line will not be executed if there is no program line number. The prompt "Modify> " will be displayed to remind you that the .M command is active.

The program line modification prompt can be configured via the BBPROMPTM environment variable.

Example

* $l

% list

  1PRINT "hello"

  2PRINT "goobye"

% list 2

  2PRINT "goobye"

% .m

Modify> PRINT "goobye"<cursor here - correct line>

% list

  1PRINT "hello"

  2PRINT "goodbye"

%

See also

. | .A | .C
.E | .I | .N
.NA | .NB | .P
BBPROMPTM |  |

Appendix J - U/BL Line Editing Commands


.N

.N ---------- Add a line after the currently LISTed line

Type

U/BL dot editor command

Syntax

.N

Description

Typing .N at the U/BL * prompt displays the program line editing prompt '>' on the next line. The .N dot editor command works as follows:

  • No program is LOADed in memory:

Program editing starts at the > prompt. Press <RETURN> to move on to the next program line. A blank line ends the editing session. All lines typed in become the current program resident in memory.

  • A program is LOADed in memory, but none of the lines have been LISTed:

In common with the other dot editor commands, for example, .A, .C, this will generate an error 73 - Edit buffer is empty.

  • A program is LOADed in memory, and a line has been LISTed:

Program lines typed in at the > prompt are inserted after the last LISTed line.

Note: .N is not affected by BBEXTENSION=B32, unlike other dot editor commands. Also, if two .N commands are entered, then the second .N command follows on from the first, no matter what the last LISTed line was.

Example

* new

* .n

  > 1 print "hello"

  > print "goodbye"

  > 3 print "goodbye once more"

  > : enter <carriage return> here

* list

00001 PRINT "hello"

  PRINT "goodbye"

00003 PRINT "goodbye once more"

> 2 print "hello again"

  > : enter <carriage return> here

* list

00001 PRINT "hello"

  PRINT "goodbye"

00003 PRINT "goodbye once more"

00002 PRINT "hello again"

The program line editing prompt can be configured via the BBPROMPTN environment variable. For example:

* new

* .n

  > print "hello"

  > : enter <carriage return> here

* list

PRINT "hello"

* .n

  > print "goodbye"

>

* list

PRINT "hello"

PRINT "goodbye"

* .n

  > print "hello again"

  >

* list

PRINT "hello"

PRINT "goodbye"

PRINT "hello again"

* $l

% list

  1 PRINT "hello"

  2 PRINT "goodbye"

  3 PRINT "hello again"

% list 2

  2 PRINT "goodbye"

% .n

  > print "this will appear after line 2"

  >

% list

  1 PRINT "hello"

  2 PRINT "goodbye"

  3 PRINT "this will appear after line 2"

  4 PRINT "hello again"

% new

% $l

* .n

  > 10 print

  >

* list

00010 PRINT

* .n

  > 5 print x

  > print "Second line

  >

* list

00005 PRINT X

  PRINT "Second line"

00010 PRINT

See also

. | .A | .C
.E | .I | .M
.NA | .NB | .P
BBPROMPTN |  |

Appendix J - U/BL Line Editing Commands


.NA

Type

U/BL dot editor command

Syntax

.NA

Description

Typing .NA at the U/BL '*' prompt displays the program line editing prompt '>' on the next line. The .NA command works as follows:

  • No program is LOADed in memory:

Program editing starts at the > prompt. Press new-line to move on to the next program line. A blank line ends the editing session. All lines typed in become the resident program resident in memory.

  • A program is LOADed in memory, but none of the lines have been LISTed:

In common with the existing dot editor commands, for example, .A, .C, etc this generates an error 73 - Edit buffer is empty.

  • A program is LOADed in memory, and a line has been LISTed:

Program lines typed in at the > prompt are inserted after the last LISTed line.

Example

* new

* .na

  > print "hello"

  >

* list

PRINT "hello"

* .na

  > print "goodbye"

  >

* list

PRINT "hello"

PRINT "goodbye"

* .na

> print "hello again"

  >

* list

PRINT "hello"

PRINT "goodbye"

PRINT "hello again"

* $l

% list

  1 PRINT "hello"

  2 PRINT "goodbye"

  3 PRINT "hello again"

% list 2

  2 PRINT "goodbye"

% .na

  > print "this will appear after line 2"

  >

% list

  1 PRINT "hello"

  2 PRINT "goodbye"

  3 PRINT "this will appear after line 2"

PRINT "hello again"

See also

. | .A | .C
.E | .I | .M
.N | .NB | .P
BBPROMPTN |  |

Appendix J - U/BL Line Editing Commands


.NB

.NB ---------- Inserts a line before the currently LISTed line

Type

U/BL dot editor command

Syntax

.NB

Description

Typing .NB at the U/BL * prompt displays the program line editing prompt (>) on the next line. The .NB dot editor command works as follows:

  • No program is LOADed in memory:

Program editing starts at the > prompt. Press new-line to move on to the next program line. A blank line ends the editing session.

  • A program is LOADed in memory, but none of the lines have been LISTed:

Program lines typed in at the > prompt are added to the end of the program.

  • A program is LOADed in memory, and a line has been LISTed:

Program lines typed in at the > prompt are inserted before the last LISTed line.

Example

* new

* .nb

  > print "hello"

  >

* list

PRINT "hello"

* .nb

  > print "before the last LISTed line"

  >

* list

PRINT "before the last LISTed line"

PRINT "hello"

* .nb

> print "between the other two lines"

  >

* list

PRINT "before the last LISTed line"

PRINT "between the other two lines"

PRINT "hello"

* $l

% list

  1 PRINT "before the last LISTed line"

  2 PRINT "between the other two lines"

% list 2

  2 PRINT "between the other two lines"

% .nb

  > print "this will appear before line 2"

  >

% list

  1 PRINT "before the last LISTed line"

  2 PRINT "this will appear before line 2"

  3 PRINT "between the other two lines"

  4 PRINT "hello"

See also

. | .A | .C
.E | .I | .M
.N | .NA | .P
BBPROMPTN |  |

Appendix J - U/BL Line Editing Commands


.P

.P ---------- Display the contents of the dot editor buffer

Type

U/BL dot editor command

Syntax

.P

Description

The .P command displays the contents of the dot editor buffer but does not change it. The contents of the dot editor buffer are the last line typed in from the keyboard, or the line displayed by a LIST line_number statement.

U/BL generates an error 73 if .P is used when the line buffer is empty.

When the terminal type is 8 (see BBTTYPE), CTRL-A offers an alternative method of displaying and editing the last line listed or the last line typed (if the BBEXTENSION environment variable includes B32).

Example

* 10 print "Hello,";

* 20 print " World"

* list

00010 PRINT "Hello,";

00020 PRINT " World"

* .p

00020 PRINT " World"

* list 10

00010 PRINT "Hello,";

* .p

00010 PRINT "Hello,";

See also

. | .A | .C
.E | .I | .M
.N | .NA | .NB
BBTTYPE | BBEXTENSION |

Appendix J - U/BL Line Editing Commands


@ACTION

@ACTION ----------- Allows a user to specify an action using a screen menu

Type

U/BL Command.

Syntax

@ACTION first_field,number,menu_string[,current_field]

Arguments

first_field | A numeric expression specifying the field specs of the first field prompt to display.
number | A numeric expression specifying the number of action fields to choose from.
menu_string | A string variable, which contains the choices.
current_field | This is an optional numeric expression which is used to specify the first of the displayed prompts which the cursor will be initialized to. If this is not specified, the current field is initialized to 1.

Description

The @ACTION command allows the user to choose one of a number of items. The prompts to be output are contained in the menu_string parameter. The characters within the menu to display and the location of the display are determined by the field specs which are specified by the @SET (or @SETFD/@SETSD) statements.

The @ACTION displays the current field exactly as the @PRINT command, and then positions the cursor at the beginning of the displayed field. If the user enters unpend 4 or special key 3 (normally UP ARROW and LEFT ARROW respectively), the display backs up. This means that the previous field is displayed, and the cursor positions to the start of the field. Backing up while at the first field will wrap around to the last field. If the user enters unpend 2 or special key 4 (normally line feed and RIGHT ARROW respectively), or the space bar, the display moves forward. This means that the next field is displayed and the cursor positions to the start of the field. Moving forward while at the last field will wrap around to the first field.

If the user enters unpend 1 or unpend 3 (normally the CR and ESC keys respectively), the @ACTION command terminates and the #FIELD variable is set to the field number relative to 1 and the first field number. In other words, #FIELD=1 if the unpend character is entered for the first field;#FIELD=2 if the unpend character is entered for the second field, and so on.

If the alternate '@' value flag is set, the action choice is displayed using the alternative '@' value. The default values are 44 (to display the choices in reverse video), and 45 (to change back to normal video display).

Note: The @ ACTION only displays the current field until the user moves forward or backs up. In order to display all the choices on the screen at one time, use the @PRINT command.

If the current field is specified, and its value is zero, the cursor will position to the last prompt. If current field is less than zero or greater than the number of prompts, the cursor will start out positioned to the first prompt.


$ASX

$ASX ---------- Converts a string to a number with high order sign

Type

U/BL function

Syntax

$ASX(str$)

Arguments

str$

A string or string variable.

Description

This function converts a string containing a binary representation of a signed integer to a signed integer. It returns the same values as the ASC function when the high order bit is off, and returns a negative number when the high order bit is on.

Use the $ASX function when converting a string that contains the binary value of a number, which may be negative. It can be used either in a statement or from the keyboard.

On systems with little-endian architecture, for example, Intel 80x86, U/BL reverses the byte order to produce the correct numeric value.

Examples

A comparison of the ASC and $ASX functions:

* print asc("<89>"),$asx("<89>")

89 89

* print asc("<112>"),$asx("<112>")

112 112

* print asc("<129>"),$asx("<129>")

129 -127

* print asc("<130>"),$asx("<130>")

130 -126

* print asc("<132>"),$asx("<132>")

132 -124

* print asc("<144>"),$asx("<144>")

144 -112

* print asc("<255>"),$asx("<255>")

255 -1

Converting from a negative integer to a string and back again:

* list

00010 DIM I$[10]

00020 LET I$=CHR$(-40,1)

00030 PRINT ASC(I$),$ASX(I$)

* run

216 -40

In triple precision:

* list

00005 $PUTENV "BBPRECISION","6"

00010 DIM I$[10],J$[10]

00020 LET I$=CHR$(-1,4) \ J$=CHR$(-1,8)

00030 PRINT "ASC","$ASX","ASC","$ASX"

00040 PRINT ASC(I$),$ASX(I$),ASC(J$),$ASX(J$)

00050 LET I$=CHR$(-40000,4) \ J$=CHR$(-4000000,8)

00060 PRINT ASC(I$),$ASX(I$),ASC(J$),$ASX(J$)

* run

ASC $ASX ASC $ASX

4294967295 -1 -1 -1

4294927296 -40000 -4000000 -4000000

See also

ASC

CHR$


ABS

ABS ----------- Returns the absolute value of a numeric expression

Type

U/BL function

Syntax

ABS(num)

Arguments

num

A numeric expression

Description

The ABS function returns the absolute value of a numeric expression. The absolute value is the magnitude of a number without positive or negative being considered. ABS returns a positive result whether its argument is positive or negative.

Example

* print abs(-1)

1

* print abs(1)

1

See also

SGN


ADDITEM

ADDITEM ---------- Adds items to the list based Windows objects

Type

Windows Object Commands

Syntax

ADDITEM(ID, INDEX, TEXT$ [, STAT])

Arguments

ID | The unique handle of the Windows object
INDEX | The position at which the item will be inserted
TEXT$ | The textual label for the item
STAT | Optional status return

Description

Lists of items are usually stored in list boxes or combo boxes. It is often useful to be able to dynamically add or delete objects from these lists under program control. For example, the list of names in a contact name combo box would depend on which company had been chosen. The list would therefore need to be amended dependant on which customer selection the user had made. The ADDITEM command adds a new entry to a list box or combo box with INDEX determining where the new item is added. INDEX specifies how many existing options in the list appear before the new option (an INDEX of 0 adds the item as the first item in the list, 1 the second,and so on). Alternatively, specifying an INDEX of -1 will append the item to the bottom of the list.

Note: If you do have the Standard Windows Object Flags SORT style on the list box or combo box, the items may not be in the order they were declared in the creation statement.

Applies to

Combo boxes

Dropdown combo boxes

List boxes

Dropdown lists.

Example

The following example program creates a combo box with two entries, and then inserts a third entry between the first and second entries, using the ADDITEM command.

REM *** Create an initial combo box ***

COMBOBOX(1,5,5,5,20,"Initial Selection | Option 1 | Option 2",32)

REM *** Add an item between Option 1 and Option 2 ***

ADDITEM(1,1,"Option 1.5")

See Also

COMBOBOX

DELITEM

LISTBOX


ADDMENU

ADDMENU ---------- Adds a new menu item to the user menu bar

Type

Windows Object Command

Syntax

ADDMENU(DISPLAYTEXT$, RETURNTEXT$, MENU, ITEM,SUBITEM [, STAT])

Arguments

DISPLAYTEXT$ | The text to be displayed for the menu item
RETURNTEXT$ | The text to be returned when the menu item is selected
MENU | The location on the menu bar where the item will be inserted
ITEM | The location on the drop-down menu where the item will be inserted
SUBITEM | The location on any sub-menu where the item will be inserted
STAT | Optional status return

Description

The ADDMENU statement adds a new menu item to the user menu bar. The position and level of this item is defined by the settings of the MENU, ITEM and SUBITEM parameters. MENU determines the position on the menu bar that the new item will be displayed. Counting from the left the first item is MENU=0, the second MENU=1 and so on. The ITEM parameter specifies whether the item being added represents the heading text on the menu bar (ITEM=-1) or which item it is on the drop-down menu. Counting downwards the top item has a value of ITEM=0, the second ITEM=1 and so on. Finally, the SUBITEM parameter determines whether the item appears on the first drop-down menu (SUBITEM=-1) or where on a second level menu the item will be displayed. Once again the top item on the second menu is represented by SUBITEM=0.

The two string parameters define the text which is returned when the menu item is selected (RETURNTEXT$) and the text displayed on the menu (DISPLAYTEXT$). Both of these strings are free format text (with the drop-down menus being sized accordingly) but DISPLAYTEXT$ regards two characters as formatting commands. The first of these is the '&' character. This defines the following character as being the underlined accelerator key. The second format option is indicated by the '!' character and defines a separator within the current menu. To use this feature set DISPLAYTEXT$="!" and RETURNTEXT$="". Any menu item that has sub-items must not be configured to return any text. Specify "" for the RETURNTEXT$ parameter.

Note: This statement will not change the displayed menu bar unless you have switched from USER to SYSTEM using a SETGUIOPT 8 call.

You can call the existing U/Gi system menu items (note, items not menus) by using the following mechanism. To do this, set the RETURNTEXT$ parameter to:

":&M[<menuname>\<itemname>{\<subitemname>}]"

where menuname, itemname and subitemname are the displayed names of the U/Gi system menu item to be selected. The curly braces ('{' and '}') specify optional parameters and are not to be entered.

When looking up the item's names on U/Gi's menu bar, please disregard any trailing full stop characters '.'. These are a style device to indicate that the item initiates a dialog rather than immediately carrying out an operation. They are not part of the item's name so should be ignored. For example, to replicate the menu option which brings up U/Gi's 'Comms Settings' dialog, set RETURNTEXT$ to ":&M[Preferences\Comms]" and not ":&M[Preferences\Comms&ldots;]".

Note: While Transoft will endeavor to keep the menu layouts as stable as possible, future revisions of U/Gi may change the naming and/or layout of the menus.

You can also map a menu item onto a function or other key. This is achieved by setting RETURNTEXT$ to:

":&K[<key name>]"

where <key name> is the name of the required key as listed in the U/Gi Keyboard Mapping dialog box. For example, setting:

RETURNTEXT$=":&K[alt+F1]"

will enable a menu item to act as though the <ALT> key was pressed simultaneously with function key 1.

Example

REM Define the following menu bar:

REM +---------------------------/

REM |File Connection Help \

REM +---------------------------/

ADDMENU ("&File","",0,-1,-1)

ADDMENU ("&Connection","",1,-1,-1)

ADDMENU ("&Help","",2,-1,-1)

REM Define the File menu as:

REM +-------------------+

REM |Load Connection | - Actions U/Gi's 'Load Preferences' item

REM |Save Connection | - Actions U/Gi's 'Save Preferences as' item

REM +-------------------+

REM |Exit | - Returns "%Message=bye" to the program

REM +-------------------+

ADDMENU ("&Load Connection",":&M[File\Load Preferences]",0,0,-1)

ADDMENU ("&Save Connection",":&M[File\Save Preferences As]",0,1,-1)

ADDMENU ("!","",0,2,-1)

ADDMENU ("&Exit","%Message=bye",0,3,-1)

REM Define the Connection menu as:

REM +-------------------+

REM |Comms | - Actions U/Gi's 'Comms' option

REM |Auto Logon | - ActIons U/Gi's 'Auto logon' option

REM +-------------------+

ADDMENU ("&Comms",":&M[Preferences\Comms]",1,0,-1)

ADDMENU ("&Auto Logon",":&M[Preferences\Auto logon]",1,1,-1)

REM Define the Help menu as:

REM +-------------------+

REM |Setup Help | - Actions U/Gi's help

REM |Application Help > | - Actions a second level menu

REM +-------------------+

ADDMENU ("&U/Gi Help",":&M[Help\Help]",2,0,-1)

ADDMENU ("&Application Help","",2,1,-1)

REM Define the second level Application Help menu as:

REM +-------------------+

REM |General Overview | - Returns "%Message=help" to the program

REM |Context Sensitive | - Emulates F12 keypress (calls U/BL's help)

REM +-------------------+

ADDMENU ("&General Overview","%Message=help",2,1,0)

ADDMENU ("&Context Sensitive",":&K[F12]",2,1,1)

REM Switch over to the User-defined menu set

SETGUIOPT (8,"USER")

See Also

SETGUIOPT


AERM$

AERM$ ---------- Returns an error message into a string

Type

U/BL function.

Syntax

LET str$=AERM$(err_code)

PRINT AERM$(err_code)

Arguments

str$ | A string variable which receives the error message.
err_code | The error number for which you require the string. Values in excess of 9000 represent errors specific to U/BL, and are not standard Business BASIC errors. U/BL errors are stored in the ublerm file which is specified by the BBUBBERM environment variable.

Description

The AERM$ function returns the error message associated with a particular number. The result must be assigned to a string or the function can be used as a string expression.

The AERM$ function returns the contents of the appropriate record from the BASIC.ER file. The code can also be obtained using the SYS(31) statement.

Use the AERM$ function after trapping an error from a statement equating to an operating system call. Usually, operating system calls are generated by STMC, and STME statements. For other errors, use the ERM$ function.

Example

* list

00005 DIM X$[64]

00010 LET X$=AERM$(-1)

00020 PRINT X$

00030 LET X$=AERM$(1)

00040 PRINT X$

* run

Illegal System Command

Illegal Character

See also

ERM$


AND (Logical)

AND ---------- Returns the result of a logical AND of its arguments

Type

U/BL function

Syntax

AND(num, num [,num]...)

Arguments

num

A numeric expression

Description

The AND function returns the result of a logical AND of its arguments, which are numeric expressions

The AND function compares its arguments a bit at a time. If the bits are all 1, it sets the corresponding bit of its return value. If the bit on any argument is not 1, AND clears the corresponding bit of its return value. Usually, AND is used to separate out one bit of a number. One argument is the number to be tested, and the other is a power of two corresponding to the bit to test for.

Example

The example below uses the SYS(30) statement to return the system status and tests to see if running in double precision.

* list

0010 IF AND(SYS(30),1) THEN PRINT "Double Precision" ELSE PRINT "Not Double"

* run

Double Precision

See also

OR

AND (operator)


AND (Boolean)

AND ---------- Performs a boolean AND of two expressions

Type

U/BL operator

Syntax

expr AND expr

Arguments

expr

A boolean or numeric expression

Description

The AND operator ties together two expressions, which can be boolean or numeric.

The AND operator returns a value of TRUE only if both the expressions are TRUE. A numeric expression is considered TRUE if it results in a value of anything but zero. AND may be used wherever a boolean or numeric expression is allowed. The expressions ANDed together do not need to be of the same type.

Example

01040 IF BOSS=OUT AND WORKLOAD$="Light" THEN PRINT "Put your feet up!"

See also

AND (function)

NOT (operator)

OR (operator)


ASC

ASC ---------- Returns the ASCII value of a string

Type

U/BL function

Syntax

ASC(str$)

Arguments

str$

A dimensioned string, substring or a string literal

Description

The ASC function takes the ASCII value of each byte of its string argument and moves it directly into a numeric value. Use this function to extract positive numbers from strings. The CHR$ function is used to store numbers into strings.

Note: This function only works for positive numbers. If you use negative numbers then the function produces unpredictable results. Use the $ASX function for negative numbers.

On systems with little-endian architecture, for example, Intel 80x86, U/BL reverses the byte order to produce the correct numeric value.

Examples

1. The first examples below demonstrate printing the ASCII values of some characters:

* ;ASC("A")

65

* ;ASC("B")

66

* ;ASC("Z")

90

2. This next example demonstrates storing a number in a string and then retrieving it:

00010 DIM A$[512]

00020 INPUT "Enter a positive number...",B

00030 LET A$=CHR$(B,4),FILL$(0)

00040 BLOCK WRITE A$

00050 REM other program statements might go in here

00150 BLOCK READ A$

00160 LET B=ASC(A$[1,4])

00170 PRINT "The number extracted is";B

00180 GOTO 00020

* run

Enter a positive number...23

The number extracted is 23

See also

$ASX

CHR$


AUTOLOCK FILE

AUTOLOCK FILE ---------- Toggles automatic record locking on or off

Type

U/BL statement

Syntax

AUTOLOCK FILE(channel) ON

AUTOLOCK FILE(channel) OFF

Arguments

channel

A numeric expression which contains the channel number on which a file is open

Description

The AUTOLOCK statement toggles automatic record locking for the file opened on the specified channel. When AUTOLOCK is on:

  • An SLOCK is automatically performed for every record that is read from the file, except those records read with a READ or INPUT statement.

  • No other users are able to access the record.

When the record has finished processing, you must perform a SUNLOCK.

You cannot use both the READLOCK and the AUTOLOCK statements at the same time. The AUTOLOCK statement only has any effect when READLOCK is turned off. If you try to lock a record that is already locked by another task, the BASIC error (#-157) is generated.

Example

This example demonstrates the use of the AUTOLOCK statement. This file is being opened in shared mode, allowing other users to process. Record 1 is read and is automatically locked by the system. The record is then updated and rewritten. A SUNLOCK is then executed to release the record.

05 DIM REC$ (80)

10 OPEN FILE (0, 5) ,"FILE.DT" : Shared-use open mode

20 AUTOLOCK FILE (0) ON : Turn locking on

30 RECNUM = -1 : Init record pointer

40 RREAD FILE (0, RECNUM) ,REC$ : Read record and lock it. Test for record already locked. :

50 REC$ (40, 80) = FILL$ (0) : Modify record

60 RWRITE FILE (0, RECNUM) ,REC$ : Update and rewrite record

70 SUNLOCK FILE (0, RENUM) : Release record

90 CLOSE


AXCALL

AXCALL ---------- Call an ActiveX control method

Type

ActiveX Command

Syntax

AXCALL(ID, METHOD$, <RETVAL>, STAT, [<PARAM1>,..,<PARAM n>]

Arguments

ID | The handle of a previously created ActiveX control.
METHOD$ | The name of the method to be called.
<RETVAL> | A string or numeric variable to receive the return from the method, if there is one. This will depend on the method called. If the method returns no value or the return value is not required, a constant (such as a number (0) or an empty string "") must be placed here. This improves performance as U/Gi does not have to return the data.
STAT | The status return.
<PARAMx> | Optional parameters to be passed to the method. These depend on the method called.

Description

The AXCALL statement calls a method of an ActiveX control. A method is a function associated with a particular control that will change the state of the control. A typical example would be the Navigate method of the Internet Explorer control that directs it to a Web page, taking the URL of the Web page as its parameter.

See the Active X Tutorial 2. Controlling the Internet Explorer.

Each of an ActiveX controls methods has a different set of parameters that are documented by the controls' provider. Windows will attempt to translate between the basic U/BL types and some of the more complicated Windows types, but this will not always be possible. However, the basic number and string types are usable for most general-purpose applications.

Some controls require that values be passed by reference; that is, the control can update the value that is passed through as a parameter. In this case, the value passed must be a variable and not a number or string literal . This will be described in the documentation provided by the control creator.

Properties of controls may be more complex than simple types, and have methods themselves. These may be called by using the name of the method after the property name, separating them with a period (.), for example, MyProp.Method.

Properties that are indexed (and with multiple indexes) and have sub-properties (or sub-methods, which is common) need to have some way of indicating the number of indices used to access the property in order to separate them from further parameters following the indices. This is done by adding dummy "parameter lists" after the property to indicate only the number of parameters. For example, a method call on a property that has one index must be referenced as MyProp(a).Method. The (a) following the Tab in the property name indicates only that there is one index used by the tab. The variable names in the parameter list are irrelevant, and only the count of variables is important, so(a,b) is the same as (b,a), (a,a) or even (z,q).

Examples

1. Calling a method with no parameters and no return type

The Microsoft ActiveX calendar control has a method called NextDay that advances the date to the next day.

10 AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

15 DELAY 10

20 AXCALL(1,"NextDay",0,STAT) : Return not required, so put a 0 in there

25 DELAY 10

30 IF STAT<>0 THEN PRINT "Call failed"

40 DELETEWO(-1)

2. Calling a method with a single string parameter

The Internet Explorer control has a method called Navigate that requires only a single URL value.

10 AXCREATE(1,5,5,10,40,"","Shell.Explorer.1","",0,STAT)

20 AXCALL(1,"Navigate",0,STAT,"http://www.microsoft.com/")

30 IF STAT<>0 THEN PRINT "Call failed"

35 DELAY 100

40 DELETEWO(-1)

3. Calling a method of a property

Assuming control 1 has a property Font with a method Clear that takes no parameters

AXCALL(1,"Font.Clear",0,STAT)

4. Calling a method of an indexed property

i) Assuming control 1 has an indexed property Row that takes a single index value. The Row property has a method Resize that has a single parameter.

AXCALL(1,"Row(a).Resize",0,STAT,ROWINDEX, NEWSIZE)

Note: The indexes go from left to right in order of how they appear in the method name.

ii) Assuming control 1 has an indexed property TextMatrix that takes two indexes, x and y, and a method ReverseString() which takes no parameters:

AXCALL(1,"TextMatrix(x,y).ReverseString",0,STAT,x,y)

iii) Assuming control 1 has an indexed property TextMatrix that takes two indexes, and a method which takes two parameters:

AXCALL(1,"TextMatrix(x,y).Method",0,STAT,x,y,PARAM1,PARAM2)

5. Using VARIANT data

An ActiveX Control method can return its data in a BYREF VARIANT ,for example, the DoGetCellData method of the EasyGrid control.

This feature works best if you pass the "buffer" into which the data is to be returned as a U/BL string. If you actually require a number, pass a string then convert that string result to a number using U/BL statements. The reason for this limitation is that the control may actually want to pass back a floating-point number and if you pass to it a VARIANT which is currently of integer type, it may fail. If you pass to it a VARIANT which is of string type, then it will succeed.

For example the following program:

WINIT

AXCREATE(444, 5, 5, 10, 35, "Easy", "EasyGrid.SGCtrl.32", "", 0)

LET V=77

LET S=0

AXCALL(444, "DoSetCellData", 0, S, 1, 1, V)

PRINT "1) S=",S

DIM W$[99]

LET W$="<unset>"

AXCALL(444, "DoGetCellData", R, S, 1, 1, W$)

PRINT "2) S=",S,"R=",R,"W$=",W$

produces the following (correct) output:

1) S= 0

2) S= 0 R=-1 W$=77

See Also

AXCREATE

AXEVENT

AXGET

AXSET


AXCREATE

AXCREATE ---------- Creates an instance of an ActiveX control

Type

ActiveX Command

Syntax

AXCREATE(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, CLSID$, LICDATA$, MODE[, STAT])

Arguments

ID | The handle that will be used to refer to this ActiveX control
ROW | The starting row of the control
COL | The starting column of the control
HEIGHT | The height of the control in character cells
WIDTH | The width of the control in character cells
TEXT$ | The default text of the control. This is usually the control's title, but it is up to the ActiveX control what it does with this. It may be ignored.
CLSID$ | The Class Identification String which identifies which ActiveX control U/BL is attempting to create.
LICDATA$ | This is a string that can be used to specify license strings for licensed ActiveX controls, and to pass control configuration data through to the ActiveX control.
MODE | A combination of the standard Windows Object flags. See Appendix C.
STAT | An optional status return (see Appendix A for possible error codes).

Description

The AXCREATE statement creates an instance of an ActiveX control, either in the current window or if the SETGUIOPT 25 statement has been used, the U/BL window in which U/Gi has been requested to create Windows Objects.

The CLSID$ argument string can take one of three forms:

Name | Format | Example
ProgID | Name$.Subname$.Version | MSCAL.Calendar.8
Version independent ProgID | Name$.SubName$ | MSCAL.Calendar
CLSID | Too long to print! | {8E27C92B-1264-101C-8A2F-040224009C02}

The CLSID and the ProgID are functionally equivalent, the ProgID being a handy reference for programmers. The Version independent ProgID refers to the use of the latest version of a control, in the case that many different versions are stored on the same PC. Transoft recommends that the version independent ProgID is used wherever possible.

Many controls require that a license string be passed to them on creation. This license string specified in the LICDATA$ parameter, must be preceded by the string LIC: (as generated by GETXTRAINF(1)), and control configuration data (as generated by GETXTRAINF(2)) should be preceded by DATA:. If both license and configuration data are required, they should be separated by a colon ':'. For example:
"LIC:0ACD12456454567:DATA:A1B400000123975CDF1"

The GETXTRAINF(1) and GETEXTRANF(2) statements can be used to obtain the license and configuration data for the ActiveX control, when designing the application.

ActiveX controls created by an AXCREATE statement can be controlled by many of the generic Windows Object commands. For example:

DELETEWO(ID) | Deletes the ActiveX control
SHOWWO(ID,SHOW) | Shows or hides the ActiveX control
ENABLEWO(ID,ENABLE) | Enables or disables the ActiveX control
SETTEXT(ID,STR$) | Sets the default text of the ActiveX control
SETEXTRAINF(ID,1,"") | Allows you to set the configuration data for the ActiveX control

Example

The following example creates the Microsoft calendar control, displays it for 10 seconds, and then deletes it:

10 AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

20 DELAY 100

30 DELETEWO(1)

See Also

AXCALL | AXEVENT | AXGET
AXSET | DELETEWO | ENABLEWO
GETXTRAINF | SETGUIOPT | SETTEXT
SETXTRAINF | SHOWWO |

Windows Object Errors

Windows Object Flags


AXEVENT

AXEVENT ---------- Specify event(s)

Type

ActiveX Command

Syntax

AXEVENT(ID, EVENTNAME$, EVENTID, MAP$ [,STAT])

Arguments

ID | The handle of the previously-created ActiveX control
EVENTNAME$ | The name of an event the ActiveX control generates
EVENTID | Specifies the value returned as a Windows object message to U/BL, when the ActiveX control generates the particular event.
MAP$ | A string to map event parameters. If MAP$ is a minus sign, the parameters passed into the event by the ActiveX control are converted into strings and passed after the message, separated by semicolons.
STAT | An optional return code

Description

ActiveX controls can generate events that signal that some change of state has occurred on the ActiveX control. The change of state could be a response to a user clicking the control, the expiration of a timer, or an external event such as the delivery of a mail item. The AXEVENT command allows you to specify which events you wish to listen out for, and how you want to be notified of them.

When an event that has been flagged by an AXEVENT command as being of interest to the U/BL program occurs, a message of the following form is returned:

@^<ID>;<EVENTID>;

where:

<ID> | is the Windows Object handle of the ActiveX control
<EVENTID> | is the value passed in the EVENTID flag of the AXEVENT statement.

In this way, events can be uniquely identified amongst several that a single control could generate.

Some events pass through parameters by reference that can in principle be changed. These are not currently supported.

Example

The Microsoft Calendar Control calls the AfterUpdate event when the selected date changes. The following example program prints the date on the screen when the date is changed.

00005 PRINT @(-30);"* Calendar Control Event Handling *"

00006 DELETEWO(-1)

00010 AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

SETGUIOPT(5,"<10>") : Set return terminator

AXEVENT(1,"AfterUpdate",5,"",STAT)

DIM A$[100]

@loop

STMA 6,0

INPUT USING "","",A$

STMA 7,0

IF A$="@^1;5;" THEN

AXGET(1,"Value",A$)

PRINT @(23,1);A$;

PRINT @(2,1)

GOTO @loop

END IF

See Also

AXCALL | AXCREATE | AXGET
AXSET |  |


AXGET

AXGET ---------- Retrieve the value of an ActiveX control's property

Type

ActiveX Command

Syntax

AXGET(ID, PROP$, <VAL>, STAT, [ <PARAM1>,..,<PARAM n>]

Arguments

ID | The handle of the previously-created ActiveX control.
PROP$ | The name of the property to be retrieved.
<VAL> | A string or numeric variable that will receive the value of the property. How this is interpreted depends on the type of the property.
STAT | The status return.
<PARAMx> | Optional parameters to be passed to the method. Used for those ActiveX controls whose properties are accessed like arrays.

Description

Each ActiveX control has a set of values associated with it known as properties. Properties can be read from and written to, and are used to change the state of the control. The AXGET command is used to retrieve the value of a property into a variable.

Note: In exceptional circumstances some ActiveX controls properties may be write-only.

Each ActiveX control property has a different data type that is documented by the controls' provider. U/BL will attempt to translate between the basic data types provided by U/BL and some of the more complicated Windows types, but this will not always be possible in all cases. However, the basic number and string types are usable for most general-purpose applications.

Some controls have indexed properties that take parameters. For example, a multi-line edit box may have a Text property that has an index that specifies which line is being referred to. Properties may also have sub-properties themselves; for example, a Font property will often have sub-properties such as Name and Size. To identify sub properties to the AXGET statement each element in a property name must be separated by a period '.', for example, Font.Size

Properties that are indexed need to have some way of indicating the number of indices used to access the property in order to separate them from further parameters following the indices. This is done by adding place holders after the property to indicate the number of indices. For example, a method call on a property that has one index must be referenced as MyProp(a).Method. The (a) following the Tab in the property name indicates only that there is one index used by the tab. The variable names in the parameter list are irrelevant, and only the count of variables is important, so (a,b) is the same as (b,a), (a,a) or even (z,q).

Note: The variables used in the argument list are irrelevant. It is only the number of arguments that count.

Example

Example 1: Getting an ActiveX control property

The following example retrieves the day from the Microsoft calendar control:

AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

MESSAGEBOX("Please change the date","",STAT)

DELAY 100

AXGET(1,"Day",DAY)

PRINT "Day was ",DAY

Example2: Indexed property

To retrieve the grid element at a particular row and column from the MSFlexGrid control:

AXCREATE(1,5,5,10,40,"MSG","MSFlexGridLib.MSFlexgrid","",1,STAT)

AXGET(1,"Rows",ROWS)

AXGET(1,"Cols",COLS)

PRINT "Rows - ",ROWS

PRINT "Cols - ",COLS

See Also

AXCALL | AXCREATE | AXEVENT
AXSET |  |


AXSET

AXSET ---------- Set an ActiveX control property

Type

ActiveX Command

Syntax

AXSET(ID, PROP$, <VAL>,STAT, [ <PARAM1>,..,<PARAM n>]

Arguments

ID | The handle of the previously created ActiveX control
PROP$ | The name of the property to be set
<VAL> | A string or numeric variable or value to which the property will be set. How this is interpreted will depend on the property type.
STAT | The status return
<PARAMx> | Optional index parameters to be passed to the method. Used for those ActiveX controls whose properties are indexed like arrays.

Description

Each ActiveX control has a set of values associated with it known as properties. Properties can be read from and written to, and are used to change the state of the control. The AXSET command is used to set a property on a control to a specific value.

Note: Some properties may be read-only, and in exceptional cases write-only.

Each ActiveX control property has a different data type that is documented by the controls' provider. U/BL will attempt to translate between the basic data types provided by the language and some of the more complicated Windows types, but this will not always be possible in all cases. However, the basic number and string types are usable for most general-purpose applications.

Some controls have indexed properties that take parameters. For example, a multi-line edit box may have a Text property that has an index that specifies which line is being referred to. Properties may also have sub-properties themselves; for example, a Font property will often have sub-properties such as Name and Size. To identify sub properties to the AXSET statement each element in a property name must be separated by a period '.', for example, Font.Size

Properties that are indexed need to have some way of indicating the number of indices used to access the property in order to separate them from further parameters following the indices. This is done by adding place holders after the property to indicate the number of indices. For example, a method call on a property that has one index must be referenced as MyProp(a).Method. The (a) following the Tab in the property name indicates only that there is one index used by the tab. The variable names in the parameter list are irrelevant, and only the count of variables is important, so (a,b) is the same as (b,a), (a,a) or even (z,q).

Note: The variables used in the argument list are irrelevant. It is only the number of arguments that count.

Example

Example 1: Setting an ActiveX control property

The following example sets the day value in the Microsoft Calendar Control to the 15th day of the month.

AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

AXSET(1,"Day",15)

Example2: Indexed property

The MSFlexGrid control has an indexed property that sets the grid element at a particular row and column:

AXCREATE(1,5,5,10,40,"MSG","MSFlexGridLib.MSFlexgrid","",1,STAT)

REM **** Do the basic setup on the control

AXSET(1,"Rows",5)

AXSET(1,"Cols",5)

REM *** Set element (2,3) to Hello

AXSET(1,"TextMatrix","Hello",STAT,2,3)

See Also

AXCALL | AXCREATE | AXEVENT
AXGET |  |


@BLANK

@BLANK ---------- Blanks or zeroes the screen format fields

Type

U/BL statement.

Syntax

@BLANK(fld,blnk[,rec$])

Arguments

fld | A numeric expression indicating the first field to be blanked.
blnk | A numeric expression indicating the number of fields to be blanked.
rec$ | An optional string variable. If used, the fields are blanked within the string. If rec$ isn't used, the blanks are displayed at the appropriate places on the screen.

Description

The @BLANK statement blanks or zeroes the specified number of fields starting with the specified first field. It is used in conjunction with the @INPUT and @PRINT statements.

The @BLANK statement outputs blanks or zeros to the screen, if the optional rec$ parameter is not specified. The location of the blanks is specified by the field specs defined by the @SET or @SETSD statements. If the optional rec$ parameter is specified blanks or nulls are output to the rec$ string at the location specified by the field specs. If the field type is alpha, blanks are moved, otherwise nulls are moved.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

:

00140 @BLANK(1,1,CAT$)

00150 @BLANK(1,1)

00160 @INPUT(1,1,CAT$)

:

See also

@INPUT

@PRINT


$B

$B ----------- Set a breakpoint

Type

U/BL command.

Syntax

$B line_id

Arguments

line_id

An expression specifying a program line number or label

Description

The $B command sets a break point prior to executing the line specified in the line_id argument. U/BL will break each time it encounters a program line with that number or label.

After setting a break point and RUNning a program, you can step through lines of code with the $N command.

Setting a break point on a label and then running another program may not work as expected. This is because U/BL stores an index number for the label, and so when another program is LOADed, the index number set when the break point was created is likely to refer to a different label in the new program.

Note: The $L command affects break point setting. When $L is active, break points set from the $B command are based on physical line numbers, rather than program line numbers.

See also

$N

$T


BLOCK READ FILE

BLOCK READ FILE ---------- Read data blocks from a file

Type

U/BL command or statement

Syntax

BLOCK READ FILE(channel[,start_pos]),var

Arguments

channel | A numeric expression representing the channel number of an open file.
start_pos | A numeric expression representing the block number in a file to begin READing at.
var | A string variable or substring with a length of at least 512 bytes, or an array variable which holds at least 512 bytes. If the variable is too small, an error 55 "Block I/O error" occurs.

Description

The BLOCK READ FILE command reads as many full blocks from a file as it can fit into the variable. If, for example, X$ is DIMensioned to 1024 bytes, two blocks will be read into it. If X$ is DIMensioned to 1023 bytes, only one block will be read into it.

If the start_pos argument is specified, the BLOCK READ FILE command begins reading from that block number, otherwise it begins reading at the start of the file. The position in the file (as returned by GPOS) is undefined after a BLOCK READ FILE command.

BLOCK READ FILE[16] is an exceptional case which behaves as a BLOCK READ statement; it reads data from the common area.

Example

* list

00010 DIM NUMBERS[63]

00020 FOR I=0 TO 63

00030 NUMBERS(I)=RND(100)

00040 TOTAL=TOTAL+NUMBERS(I)

00050 NEXT I

00060 OPEN FILE[0,10],"testfile"

00070 BLOCK WRITE FILE[0],NUMBERS

00080 CLOSE

00090 PRINT "The sum of the numbers written to the file is ";TOTAL

* run

The sum of the numbers written to the file is 2301

00010 DIM ARRAY[63]

00020 OPEN FILE[0,10],"testfile"

00030 BLOCK READ FILE[0],ARRAY

00040 CLOSE

00050 FOR I=0 TO 63

00060 SUM=SUM+ARRAY(I)

00070 NEXT I

00090 PRINT "The sum of the numbers read from the file is ";SUM

* run

The sum of the numbers read from the file is 2301

See also

BLOCK READ

BLOCK WRITE

BLOCK WRITE FILE

GPOS

READ FILE


BLOCK READ

BLOCK READ ---------- Read data blocks from the common area

Type

U/BL command or statement

Syntax

BLOCK READ var

Arguments

var

A DIMensioned string variable or substring with a length of at least 512 bytes, or and array variable which holds at least 512 bytes. If the variable is too small, an error 55 - Block I/O error - occurs.

Description

The BLOCK READ command retrieves up to four 512 byte blocks of data written to the common area by another program with a BLOCK WRITE statement.

Use the common area to share up to 2048 bytes of data between programs. Data is put into the common area with a BLOCK WRITE statement and remains there until the user logs off or it is overwritten by a further BLOCK WRITE. Many utility programs use the common area; its contents may be overwritten by these utilities. BLOCK READ retrieves the contents of the common area so that a program can use the data.

On the UNIX and DOS platforms, use the BBCOMMON environment variable to expand the common area from its default size of 512 bytes.

Example

* load "test1

* list

00010 REM TEST1

00020 DIM X$[512]

00030 LET X$="Test data!",FILL$(0)

00040 BLOCK WRITE X$

00050 SWAP "TEST2"

* load "test2

* list

00010 REM TEST2

00020 DIM Y$[512]

00030 BLOCK READ Y$

00040 PRINT Y$

00050 PRINT

* load "test1

* run

Test data!

See also

BBCOMMON

BLOCK READ FILE

BLOCK WRITE

BLOCK WRITE FILE


BLOCK WRITE FILE

BLOCK WRITE FILE ------------ Write data blocks to a file

Type

U/BL command or statement

Syntax

BLOCK WRITE FILE(channel[,start_pos]),var

Arguments

channel | A numeric expression representing the channel number of an open file.
start_pos | A numeric expression representing the block number in a file to begin writing at.
var | A dimensioned string variable or substring with a length of at least 512 bytes, or an array variable which holds at least 512 bytes. If the variable is too small, an error 55 "Block I/O error" occurs.

Description

The BLOCK WRITE FILE command writes as many full 512-byte blocks from a file as it can fit into the variable. If, for example, X$ is DIMensioned to 1024 bytes, two blocks will be written from it. If X$ is DIMensioned to 1023 bytes, only one block will be written into it.

If the start_pos argument is specified, the BLOCK WRITE FILE command begins writing from that block number, otherwise it begins writing at the start of the file. The position in the file (as returned by GPOS) is undefined after a BLOCK WRITE FILE command.

Example

See BLOCK READ FILE

See also

BLOCK READ

BLOCK READ FILE

BLOCK WRITE

GPOS

WRITE FILE


BLOCK WRITE

BLOCK WRITE ---------- Write data blocks to the common area

Type

U/BL command or statement

Syntax

BLOCK WRITE var

Arguments

var

A DIMensioned string variable or substring with a length of at least 512 bytes, or and array variable which holds at least 512 bytes. If the variable is too small, an error 55 - Block I/O error - occurs.

Description

The BLOCK WRITE command places up to four 512 byte blocks of data into the common area for another program to retrieve with a BLOCK READ statement.

Use the common area to share up to 2048 bytes of data between programs. Data is put into the common area with a BLOCK WRITE statement and remains there until the user logs off or it is overwritten by a further BLOCK WRITE. Many utility programs use the common area; its contents may be overwritten by these utilities. The BLOCK READ command retrieves the contents of the common area so that a program can use the data. It is not possible to write to a specific part of the common area; each BLOCK WRITE statement starts at the beginning of the area.

On the UNIX and DOS platforms, use the environment variable BBCOMMON to expand the common area from its default size of 512 bytes.

Example

See BLOCK READ

See also

BBCOMMON

BLOCK READ

BLOCK READ FILE

BLOCK WRITE FILE


BOX

BOX ------------ Provide line and box drawing characters

Type

U/BL command or statement

Syntax

BOX(ru,cu,rl,cl[,stat[,flag]])

Arguments

ru | row of upper corner, relative to row 1 of the screen
cu | col of upper corner, relative to column 1 of the screen
rl | row of lower corner, relative to row 1 of the screen
cl | col of lower corner, relative to column 1 of the screen
stat | receives the error code
flag | An optional numeric variable that can be set to 1 if you want the area of the screen where the box is to be displayed to be cleared when the box is displayed, or set to 0 if you do not want that area of the screen cleared

Description

Note: When running U/BL within U/Gi, the MSLineDraw font must be installed if the BOX statement is used.

The BOX statement allows you to use line and box drawing characters to enhance the appearance of your windows and screens. When:

ru=rl this defines a horizontal line

cu=cl this defines a vertical line

Where multiple lines cross, the appropriate graphic characters are used. These additional graphic characters are defined in the TDF Terminal Definition File by 5 further characters in the box line positions 8 to 12. Examples of the graphic characters used:

In a DEC VT100 TDF:

gron lb,28,30

groff lb,28,42

box=6c,6b,6d,6a,71,71,78,74,75,77,76,6e

In a Dasher D4xx series TDF:

gron le,46,53,31,31

groff le,46,53,30,30

Box Position | Box Position
1 Top left hand | 7 Vertical
2 Top right hand | 8 Left intersection
3 Bottom left hand | 9 Right intersection
4 Bottom right hand | 10 Top intersection
5 Top horizontal | 11 Bottom intersection
6 Bottom horizontal | 12 Cross

Note: On Wyse-50 terminals character attributes will be carried on into the box unless the TDF keyword wysebox is set to 1b,47,30 in the TDF.

If you are not in GUI mode the escape sequences (as described above) are used to draw the box. If escape sequences are not defined then the '+' (for the corners), '-' (for horizontal lines) and the '|' (for vertical lines) characters are used to draw the box.

If you are using GUI mode then U/Gi will draw the box graphically using the following line types:

  • thin

  • thick

  • recessed

  • raised

The appearance of the lines can be selected using the SETGUIOPT 20 statement, or from the Boxes and Borders property page of the General Preferences property sheet on U/Gi.

Example

The example below applies to U/BL running within U/Gi (on UNIX U/Gi must be invoked with the '-g' flag).

@Draw_Box

LET RU=10                           :Row number of top of box

LET CU=1                            :Column number of left of box

LET RL=20                           :Row number of top of box

LET CL=80                           :Column number of right of box

SETGUIOPT(20, "3,3")                :Set box character style to recessed

SETGUIOPT(20, "0, 255 255 255")     :Set box background colour

SETGUIOPT(20, "4")                  :Redraw all boxes on the screen

BOX(RU,CU,RL,CL,STAT)               :Draw box

IF STAT THEN GOSUB @Error_Routine

RETURN

See also

SETGUIOPT 20


BUTTON

BUTTON ----------- Create buttons, check boxes, or group boxes

Type

Windows Object Command

Syntax

BUTTON(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, MODE [, STAT [, RETURNTEXT$] ])

Arguments

ID | The unique handle used to identify the object
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT$ | Specifies the display on the buttons face.
MODE | Specifies how the statement (and subsequently, the object) works.
STAT | Optional status return.
RETURNTEXT$ | Specifies what will be returned if the RETURNTEXT flag is used.

Description

The BUTTON statement is used to create Windows buttons, check boxes, and group boxes. The operation of this statement is determined by the MODE parameter, which is a bitmask that determines, what type of object is created, how it is drawn and how it operates. The MODE parameter can be set to one of the following values:

Value

Description

0

Creates a button with a textual legend specified by the contents of the TEXT$ parameter.

Optionally can be used to specify a keyboard shortcut-key. To do this precede the character you want to define as the short cut key, by the & character in the TEXT$ string. For example, if:

TEXT$="St&art"

the text will appear on the button as St a rt. Pressing the ALT and A keys will action the keyboard shortcut.

Note: You need to explicitly enable shortcuts by calling the SETGUIOPT 13 statement.

For bitmap buttons, accelerator keys are also supported and are defined by appending the accelerator to the end of the comma-separated list of bitmaps. For example:

TEXT$="<path BMP1>,<path BMP2>,<path BMP3>,<path BMP4>,&<key>"

or if not, all four different bitmaps are defined:

TEXT$="<path BMP>,,,,&<key>"

As no text is displayed on a bitmap button, the accelerator key is not displayed on such a button.

32

Creates a bitmap button with TEXT$ specifying the bitmap or bitmaps to be displayed. Up to four bitmaps may be specified, one for each possible state of the button:

  • normal

  • selected

  • focused·

  • disabled

The TEXT$ parameter holds a comma separated list of the '.BMP' file pathnames. The pathnames can be local to the client PC; UNC paths or URLs (either http or ftp protocol), for example:

C:\BMPS\Normal.bmp, \\PC\Bmps\Selected.bmp, http://site/Bmps/focused.bmp, dtp://site2/Bmps/disabled.bmp

Optionally you can specify a keyboard shortcut-key for the bitmap button, by putting a &<key> (where, key is the key you want to define as the shortcut key) at the end of the comma separated list of the '.BMP' file pathnames. For example, use:

C:\Bmps\1.bmp, C:\Bmps\2.bmp, C:\Bmps\3.bmp, C:\Bmps\4.bmp,&b

Pressing the ALT and B keys, actions the keyboard shortcut for the bitmap button above. If the BUTTON command is not being used to define four bitmaps for the button, four commas must still be specified in the TEXT$ parameter, for example:

1bitmap="C:\BMPS\1.bmp,,,,$b"

To enable keyboard shortcuts the SETGUIOPT 13 function must be used.

Note: As U/Gi 3.10 is a 16-bit application, it cannot use long filenames or pathnames containing spaces. You must only use the short name version (MS/DOS 8+3 format) of the pathname for any bitmaps which are held in files with names in these formats. For example, use:

C:\WIN95\PROGRA~1\APP\ICON.BMP

instead of:

C:\WIN95\Program Files\APP\ICON.BMP

While U/Gi 4 can accept long pathnames, if you are using an earlier version on any client PC you must code to the lowest common denominator.

128

Creates a check box rather than a button with TEXT$ specifying the legend displayed next to the object.

384

Creates a group box rather than a button with TEXT$ specifying the name displayed on the group box.

The MODE parameter can also be combined with the standard Windows object flags or the following button specific flags:

Value | Description
512 | Returns the string @^ plus the handle of the object when it is selected
1024 | Puts a heavy border around the button
2048 | After the button is selected, puts the focus back to the current U/BL window.
16384 | If used with NOTIFYCHANGE, the contents of the RETURNTEXT$ parameter will be returned when the object is selected rather than the default, ^@<ID> message.
32768 | Results in the button returning a lost focus message of the type: @!<ctrlid> whenever the specified button loses focus. The ctrlid is the unique handle used to identify the button.
65536 | Left justify button text
131072 | Right justify button text
196608 (65536+131072) | Centre button text.

For example, to set BITMAP, NOTIFYCHANGE and AUTOFOCUS, set the MODE parameter to:

'32 U 512 U 2048' or '2592'

For bitmap buttons, MODE can also use the following flags:

Value | Description
0 | The bitmap is cropped within the size of the button
4096 | The button is scaled to the size of the bitmap
12288 | The bitmap is scaled to the button's size.

For check boxes, and group boxes, it is usual to specify the standard Windows object flag NOBORDER (OR 16 onto the value for MODE) to obtain the usual appearance of these objects.

If the button is created using the NOTIFYCHANGE and RETURNTEXT flags, it can be programmed to call the existing U/Gi system menu items. To do this, set the RETURNTEXT$ parameter to:

":&M[<menuname>\<itemname>{\<subitemname>}]"

where menuname, itemname and subitemname are the displayed names of the U/Gi system menu item to be selected.

Note: The curly braces '{' and '}' specify optional parameters and must not be entered.

When looking up the item's names on U/Gi's menu bar, please disregard any trailing full stop '.' characters. These are a style device to indicate that the item initiates a dialog rather than immediately carrying out an operation. They are not part of the item's name so should be ignored. For example, to replicate the menu option which brings up U/Gi's 'Comms Settings' dialog, set RETURNTEXT$ to:

":&M[Preferences\Comms]", and not:

":&M[Preferences\Comms...]"

Note: While Transoft will endeavor to keep the menu layouts as stable as possible, future revisions of U/Gi may change the naming and/or layout of the menus.

Another possibility when using the 'NOTIFYCHANGE' and 'RETURNTEXT' flags in combination is to enable the button to act as a key press. The return can be mapped onto a function or any other key defined in U/Gi's keyboard mapping by setting the RETURNTEXT$ parameter to:

":&K[<key name>]"

where <key name> is the name of the required key as listed in U/Gi's keyboard mapping dialog box. For example:

'RETURNTEXT$=":&K[alt+F1]"'

will enable a button or a check box to act as though the ALT key was pressed simultaneously with function key 1.

Example

REM Remove any existing Windows objects or U/BL windows
DELETEWO (-1)
WINIT (ER)

REM Define working storage
DIM NEWLINE$[1]
DIM MESSAGE$[10]

REM Draw and show window
WMAKE ("Input",6,23,16,34,7,ER)
WSHOW ("Input",ER)

REM Define the Windows objects' flags

REM Button specific flags

LET AUTOFOCUS=2048
LET NOTIFYCHANGE=512
LET GROUPBOX=384
LET CHECKBOX=128

REM Generic flags - apply to all Windows objects
LET NOBORDER=16
LET TABSTOP=1

REM Define the options as tab stop, check boxes (with no border)
LET MODE=TABSTOP+CHECKBOX+NOBORDER
BUTTON (1,4,4,1,26,"Selectable option 1",MODE,ER,"")
BUTTON (2,6,4,1,26,"Selectable option 2",MODE,ER,"")
BUTTON (3,8,4,1,26,"Selectable option 3",MODE,ER,"")

REM Define a group box to contain the check boxes
LET MODE=GROUPBOX+NOBORDER
BUTTON (4,2,2,8,29,"Available Options",MODE,ER,"")

REM Define the controlling buttons as tab stops which return

REM a message on selection and return focus to the U/BL base-panel
LET MODE=TABSTOP+NOTIFYCHANGE+AUTOFOCUS
BUTTON (5,11,6,2,8,"OK",MODE,ER,"")
BUTTON (6,11,19,2,8,"Cancel",MODE,ER,"")

REM Switch off echo (to hide button messages
SETGUIOPT 5,"<10>"
STMA 6,0

REM Allow user to edit data and wait for a button press
$DO_WHILE MESSAGE$<>"@^5;" AND MESSAGE$<>"@^6;"
INPUT "",MESSAGE$
$END_DO

REM Process button press
IF MESSAGE$="@^5;" THEN
  REM 'OK' button pressed, read the options that the user has selected
  REM Options that are selected return 1 in the appropriate variable
  GETNUMBER (1,OPTION1)
  GETNUMBER (2,OPTION2)
  GETNUMBER (3,OPTION3)
ELSE
  REM User has cancelled the operation, re-set all options
  LET OPTION1,OPTION2,OPTION3=0
END IF

REM Restore echo; close down and destroy window/objects
STMA 7,0
DELETEWO (-1)
WHIDE ("Input",ER)
WDELETE ("Input",ER)

Running the program displays the following dialog:

See Also

DELETEWO | ENABLEWO | GETNUMBER
GETTEXT | SETFOCUS | SETNUMBER
SETTEXT |  |

Windows Object error codes

Standard Windows Object Flags


BYE

BYE ---------- Exit from U/BL

Type

U/BL command and statement

Syntax

BYE

Description

The BYE command exits from U/BL and returns to its parent process. If U/BL was executed from the operating system, it returns control to the operating system.

Type BYE at the '*' prompt, or use it as a program statement to terminate the program.

Under the Windows version of U/BL, BYE can optionally request that the remote U/Gi client terminates when U/BL is shutdown. This functionality is controlled by function 19 of the SETGUIOPT statement.

Example

* bye

Terminating.

$

See also

SETGUIOPT

STMB 20


$C

$C ------------ Display the contents of the U/BL common area

Type

U/BL command.

Syntax

$C

Description

The $C command displays the contents of the U/BL common area.

See also

BBCOMMON

BLOCK_READ

BLOCK_WRITE


$CHN

$CHN ---------- Returns the next available channel

Type

U/BL function

Syntax

var=$CHN

Arguments

var

A numeric variable

Description

The $CHN function returns the next unused channel, starting from 0 and excluding 16. If all of the available channels are in use, the $CHN function returns -1.

Note: Channel 16 is reserved for the console.

On the UNIX and Windows based platforms, the number of channels per user can be set using the environment variable BBCHAN.

Example

00010 LET PRINT_CH=$CHN

00020 OPEN FILE[PRINT_CH]

00030 LET SORT_CH=$CHN

00040 OPEN FILE[SORT_CH]

See also

BBCHAN

SYS(34)


CHAIN

CHAIN ---------- Load and execute another program

Type

U/BL command or statement

Syntax

CHAIN program [THEN CON]

CHAIN program [THEN GOTO line_no]

Arguments

program | A DIMensioned string variable or sub-string, or a string literal, containing the name of a SAVEd U/BL program.
line_no | A line number in the program being CHAINed to

Description

The CHAIN command loads and executes another U/BL program. Control is not returned to the original program. The new program starts at the beginning unless THEN CON or THEN GOTO line_no is specified. Any open files remain open, with the file position pointers unchanged.

CHAIN program THEN CON | Causes the new program to begin executing from the point at which it was STOPped before the last SAVE or REPLACE. Its effect is the same as a LOAD followed by a CON.
CHAIN program THEN GOTO line_no | Causes the new program to begin at the specified line number. Variables retain the values they had at the time the program was last SAVEd or REPLACEd.

Note: Variables are not saved by default. The BBSAVE environment variable must be set to Y or the SAVEV or REPLACEV commands must be used, to enable the THEN CON and THEN GOTO commands to work with SAVEd variables.

If the new program cannot be found in the current directory or on U/BL's search paths as specified by the environment variables BBPROGS, BBSEARCH and BBPATH, the original program stays in memory and the I/O error 10 "File does not exist" occurs.

While a CHAIN statement is executing, the interrupt key is ignored. A series of small programs which CHAIN and SWAP to each other may, therefore, be difficult to interrupt.

Use the SWAP command if you want control to be returned to the original program when the new one has finished.

Use the BLOCK WRITE and BLOCK READ commands to pass data to a CHAINed program.

Example

1. Simple use of the CHAIN command.

* load "test1

* list

00010 DIM X$[512]

00020 PRINT "This is the first program"

00030 LET X$="Application Transformation"

00040 BLOCK WRITE X$

00050 CHAIN "test2"

00060 PRINT "This doesn't appear usually"

* load "test2

* list

00010 DIM Y$[512]

00020 BLOCK READ Y$

00030 PRINT "This is the second program"

00040 PRINT Y$

00050 PRINT

* run "test1

This is the first program

This is the second program

Application Transformation

2. The CHAIN command used with THEN GOTO.

* 60 chain "test1" then goto 60

* list

00010 DIM Y$[512]

00020 BLOCK READ Y$

00030 PRINT "This is the second program"

00040 PRINT Y$

00050 PRINT

00060 CHAIN "test1" THEN GOTO 00060

* replace

* run "test1

This is the first program

This is the second program

Application Transformation

This doesn't appear usually

See also

BBSAVE

BLOCK READ

BLOCK WRITE

REPLACE

REPLACEV

RUN

SAVE

SAVEV

SWAP


CHECK

CHECK ---------- Check for the existence of a disk file and return file stats information

Syntax

CHECK filespec$,fsblock$

Arguments

filespec$ | A string variable or literal containing the specification of the file to be checked
fcblock$ | A string variable to receive the FCB, dimensioned to at least 80 bytes

Description

The CHECK statement checks whether a file exists on disk or not. If the CHECK statement finds the file in either the current directory, or in any of the directories specified by the environment variables BBPATH and BBSEARCH, it will return the file's FCB information in the fcblock$ parameter. For more information about the format of the FCB block refer to the FCB$ section.

If the environment variable BBCHECKPATH is set to Y, and if the file exists, then the CHECK statement will also return the full pathname of the file in the filespec$ parameter (if it is a string, and if it has been DIMensioned large enough to hold the full path. If neither of these conditions are true, then the filespec$ parameter will remain unaltered).

If the file doesn't exist, or if the fcblock$ parameter has not been DIMensioned to at least 80 bytes, then the error 23 is returned.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

00010 DIM F$[8],FBLK$[80]

00020 LET F$,FBLK$=""

00030 CHECK ("MYFILE",FBLK$)

00040 LET F$=UCM$(FBLK$[1,8])

00050 IF F$[1,6]<>"MYFILE" THEN

00060 PRINT "FILE NOT FOUND"

00070 STOP

00080 END IF

See also

BBCHECKPATH

FCB$


CHFREEZE

CHFREEZE ---------- Release all open channels

Type

U/BL command or statement

Syntax

CHFREEZE(chan$,stat)

Arguments

chan$ | A string variable that will receive the details of the open channels.
stat | A numeric variable that will be 0 if all is OK, or non 0 if there has been an error.

Description

Note: If Large File Support is enabled then the chan$ parameter must be dimensioned to at least 4 + (84 * number of open channels). If Large File support is not enabled then the chan$ parameter must be dimensioned to at least 4 + (80 * number of open channels). Large File Support allows access to files larger than 4GB. It can be enabled by setting the BBLARGEFILES environment variable to Y and is supported by U/BL Rev 5.00 and above.

At certain points in a Basic program, it may be convenient to "freeze" all open channels so that an alternate set of files can be temporarily processed. Once this process is complete the program can reopen the channels as they were before. This facility is controlled by the CHFREEZE and CHREOPEN statements.

Any file that has been OPENed exclusively will remain exclusively held when channels are frozen. The files stay held until they are CHREOPENed. This is to ensure that files which were OPENed exclusively remain exclusive whilst they are frozen. After the first CHREOPEN, these files will be released on a subsequent CLOSE.

The CHREOPEN statement can be used repeatedly with the same chan$. For example, a CHFREEZE statement can be issued followed by a CHREOPEN and a CLOSE. The same chan$, that is, the same frozen files can be used in subsequent CHREOPEN statements, but if another user has OPENed any of the files contained in chan$ in the interim, then Basic will generate an error:

- 48 - File in use.

Note: If BBLOCKSERVER is set to Y, then chan$ can only be used once.

The number of concurrent CHFREEZE statements is limited by the amount of available memory. If a lot of CHFREEZE statements are active at any one time this can cause problems as the available memory gets used up.

Note: Unless the BBDELFILE environment variable is set, OPEN files that have been deleted from the system cannot be CHFREEZEd.

The environment variable BBFREEZE can be set to the maximum number of CHFREEZE statements which are to be allowed at any one time. The environment variable's setting is used to calculate the amount of memory which is to be allocated for use by CHFREEZE statements.

The amount of memory allocated is calculated as follows:

(BBFREEZE * BBCHAN * 8) bytes

If an attempt is made to exceed this amount, Basic will generate an error:

9198 - Too many active _CHFREEZEs.

If Large File Support is enabled then the chan$ parameter must be dimensioned to at least 4 + (84 * number of open channels). If Large File Support is not enabled then the chan$ parameter must be dimensioned to at least 4 + (80 * number of open channels).

Large File Support allows access to files larger than 4GB. It can be enabled by setting the BBLARGEFILES environment variable to Y when using U/BL Rev 5.00 and above.

Example

:

00200 CHFREEZE(CHAN$,STAT)

:

00300 CHREOPEN(CHAN$,STAT)

:

See also

BBFREEZE

CHREOPEN


CHR$

CHR$ ---------- Returns a string containing the value of a number

Type

U/BL function

Syntax

CHR$(num[,length])

Arguments

num | A numeric expression to be converted to a binary string
length | The length of the string returned. The maximum length is usually the value of BBPRECISION but up to eight characters may be generated if U/BL is emulating B32. The default if no length is specified is one.

Description

The CHR$ function is used to place a number into a string which is to be written to a file or to the common block. The number is placed in the rightmost bytes of the string. If the length specified is too short to hold a number, the string will contain the least significant bits of the number. No overflow is detected in these circumstances. If a length of more than eight is specified, a one-byte string is returned.

Use the ASC function to return a positive number from a string or substring, or the $ASX function if the number may be negative.

Note: Unless the BBEXTENSION environment variable includes B32, strings of more characters than the value of BBPRECISION cannot be generated, that is, BBPRECISION=>CHR$(Num,6) is illegal. For all illegal values for length (including values outside the range 1-8 if the BBEXTENSION environment variable does include B32) the default length of 1 is assumed.

Example

1. Show the contents of the string produced.

* list

00010 DIM X$[8]

00020 LET X$=CHR$(1)

00030 PRINT "CHR$ produces a one byte string by default"

00040 REM $H X$

00050 LET X$=CHR$(1,4)

00060 PRINT "CHR$ can produce several bytes depending on its 2nd arg"

00070 REM $H X$

* run

CHR$ produces a one byte string by default

000001 01 .

CHR$ can produce several bytes depending on its 2nd arg

000001 00 00 00 01 ....

2. Produce a fixed length record.

00050 LET REC$=CNAME$,CHR$(CNO,4),CHR$(CTYPE),CADDR$,CHR$(CLIMIT,4)

If the customer limit changes, the substring can be amended:

00120 LET REC$[75,78]=CHR$(NEW_LIMIT,4)

3. Display characters on the basis of their ASCII values.

* list

00010 FOR I=65 TO 90

00020 PRINT CHR$(I);" ";

00030 NEXT I

00040 PRINT

* run

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

4. CHR$ can be used as a string expression.

00030 IF CHR$(X)="B" THEN GOSUB 02000

See also

BBPRECISION

BBEXTENSION

ASC

$ASX

CHR$

PACK


CHREOPEN

CHREOPEN ---------- Reopens "frozen" channels and restores their details

Type

U/BL command or statement

Syntax

CHREOPEN(chan$,stat)

Arguments

chan$ | The string variable used in the corresponding CHFREEZE statement.
stat | A numeric variable that will be 0 if all is OK, or non 0 if there has been an error.

Description

At certain points in a Basic program, it may be convenient to "freeze" all open channels so that an alternate set of files can be temporarily processed. Once this process is complete the program can reopen the channels as they were before returning to the calling program. This facility is controlled by the CHFREEZE and CHREOPEN statements.

The CHREOPEN statement reopens "frozen" channels and restores their details. Any file that has been OPENed exclusively will remain exclusively held when channels are frozen.

The CHREOPEN statement can be used repeatedly with the same chan$. For example, a CHFREEZE statement can be issued followed by a CHREOPEN and a CLOSE. The same chan$, that is, the same frozen files can be used in subsequent CHREOPEN statements, but if another user has OPENed any of the files contained in chan$ in the interim, then Basic will generate an error:

- 48 - File in use.

Example

:

00200 CHFREEZE(CHAN$,STAT)

:

00300 CHREOPEN(CHAN$,STAT)

:

See also

CHFREEZE


CLEARHOTSPOTS

CLEARHOTSPOTS ------ Clear all hotspots in the current window

Type

Windows Object Command

Syntax

CLEARHOTSPOTS([STAT])

Arguments

STAT

Optional status return

Description

The CLEARHOTSPOTS command clears all hotspots defined for the current U/BL window. To clear hotspots in another window, use function 24 of the SETGUIOPT statement, to select that window, and then invoke the CLEARHOTSPOTS command to clear the hotspots in that Window. Issuing the statement SETGUIOPT (24,"") will return you to the current Window.

See Also

Windows Objects error codes

HOTSPOT


CLEARINP

CLEARINP ---------- Clears the input buffer

Type

U/BL statement.

Syntax

CLEARINP

Description

The CLEARINP statement clears the keyboard input buffer. It is equivalent to the STMA 8,4 statement.

Note: This statement is only supported when U/BL is emulating SuperDOS Business BASIC , that is, the environment variable, BBEXTENSION must be set to SDOS.

Example

See STMA 8.

See Also

BBEXTENSION


CLOSE

CLOSE ---------- Closes an open file, or all open files

Type

U/BL command or statement

Syntax

CLOSE[FILE(channel)]

Arguments

channel

A numeric expression representing the channel number of an open file.

Description

The CLOSE command complements the OPEN statement. It ends the association of a file with a channel, thus freeing the channel for re-use. The CLOSE command can be used from the keyboard or in a program.

The CLOSE command used by itself CLOSEs all files that U/BL has OPENed. It does not generate an error if there are no channels are in use. The CLOSE command also shuts any physical files which were OPENed by LOPEN statements, freeing the channel numbers used. LFTABL$ needs to be reinitialized before the logical file numbers can be reused.

The CLOSE FILE(channel) statement CLOSEs a specific file. If the channel is not in use then error 44 "File not open" occurs. If a number greater than the maximum number of channels is used for channel, error 27 "Illegal file number" occurs. The CLOSE FILE[16] statement has the same effect as a simple CLOSE command. If a program crashes, leaving files open, a CLOSE statement will be needed to CLOSE files before the program can be RUN again from the beginning.

The BYE, an NEW commands also CLOSE all open files. To find out which channels are in use, use the $F command.

Example

00050 OPEN FILE[1,10],"TESTFILE"

read from file and/or write to it

00100 CLOSE FILE[1]

See also

BYE

$F

LOPEN

OPEN

NEW


COMBOBOX

COMBOBOX ---------- Creates a combo box, dropdown combo box or dropdown list

Type

Windows Object Command

Syntax

COMBOBOX(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, MODE [, STAT])

Arguments

ID | The unique handle used to identify the object
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT$ | The initial text to be placed in the object
MODE | Specifies how the statement (and subsequently, the object) will work.
STAT | Optional status return.

Description

The COMBOBOX command is used to create Windows combo boxes, dropdown combo boxes and dropdown lists. The type of object created when using this statement is determined by the MODE parameter which is a bitmask that determines which type of object is created; how it is drawn and how it operates. The settings for MODE which determine the object's type are:

Value | Description
32 | Creates a 'simple' combo box, consisting of an edit box with a list box beneath.
64 | Creates a dropdown combo box, where the list box is hidden until an icon is pressed
96 | Creates a dropdown list; consisting of a text box with a list box beneath. Items may be selected from a list, but not changed.

When defined, the object will be located at position ROW, COL and have a size of HEIGHT, WIDTH. For a dropdown combo box or a dropdown list, the HEIGHT refers to the dropped state; the non-dropped state is of fixed vertical size.

The TEXT$ parameter determines the initial contents of the object and consists of a set of values separated by the pipe symbol ( | ). The first item in the string is taken to be the initially-selected item and is not added to the list itself. Making another selection will therefore effectively 'delete' this first option. If you wish to be able to re-select the original item you will need to add it to the list itself, otherwise the user will have to remember and manually type in the option. A manual user entry is not allowed for a dropdown list. To add the initial option to the list, specify it twice in the TEXT$ string, once as the first item and again within the main body of the list.

Note: There is a limit of 255 characters for this string; other items must be added with the ADDITEM statement. They can be deleted later with the DELITEM statement.

In addition to declaring the type of object to be created, MODE also determines how the object is drawn and how it behaves. To this end, both the Standard Windows Object Flags and some statement specific options are available. These can combined to configure the object created. To use these flag settings, simply OR their value with the value determining the object's type. For example, to create a sorted, dropdown list, which is part of the tab order set MODE to '96 U 128 U 1' or '225'. The statement specific flag options are:

Value

Description

128

The items in the list are automatically sorted. Note that this will make it difficult to refer to an item by index later

256

Any edit box (this flag does not apply to dropdown lists) will scroll left or right automatically

512

With this flag set, clicking any of the possible selections with the mouse will send a message to U/BL. For a single click (which selects the item) @^n;1; (where 'n' is the handle of the object) will be returned. Additionally, a combo box can send a message of @^n;2; (once again, 'n' represents the handle of the object) back to U/BL when an element in the list is double clicked. As drop-down lists (and drop-down combo boxes) hide the list as soon as a selection is made, it is not possible to double click an item with these controls. Hence this message can only be returned from a combo box. As double clicking a combo box item automatically selects that item (even if it was already selected), double clicking a combo box item actually sends both return messages, that is, the message sent is @^n;1;@^n;2;

1024

The object will send a message @!n back to U/BL when the user moves to another control, where 'n' is the handle of the object

2048

The object will move focus when <ENTER> is pressed.

4096

The object will move focus when <TAB> is pressed.

8192

Pressing <ENTER> selects the currently highlighted item in the list (makes it the current selection). When using this flag in combination with NOTIFYCLICKS, a @^n;1; message will be sent back to U/BL on pressing <ENTER>.

16384

Drop down-lists are searched with multiple key strings. For example, if items "ABC" and "BCD" are in the list, typing "AB" will go to "ABC" and not "BCD".

32768

Allows a SETTEXT command against a drop-down list to select an option based on an incomplete match. Normally, SETTEXT only selects an item if the text specified exactly matches a list item. For example:

00010 COMBOBOX(1,4,4,10,10,"|A-ONE|B-TWO|C-THREE",96)
00020 SETTEXT(1,"B")

Leaves no selection in the text box, while

00010 COMBOBOX(1,4,4,10,10,"|A-ONE|B-TWO|C-THREE",96+32768)
00020 SETTEXT(1,"B")

Selects B-TWO into the text box. However, a SETTEXT(1,"B-2") would leave no item selected, as there is no partial match between the list items and the parameter to SETTEXT.

For other types of combo box (those that include an edit box), this flag has no meaning; whatever text is specified at the argument to the SETTEXT command will become the contents of the box.

65536

Setting the MODE parameter to this value will result in the message '@^n;4' being issued if you attempt to move past the beginning of a combo box. The message '@^n;5' will be issued if you attempt to move past the end of a combo box.

This can be used by a U/BL program to repopulate the combobox with more options so providing a "next- page" like functionality.

Note: There is a limit on the number of editable objects (edit boxes, combo boxes and dropdown combo boxes) it is possible to display at one time. This limit depends on the operating system U/Gi runs on, but will be at least 50. In case this limit is exceeded, the error 'Out of memory on client machine' (a return code of 3) will be returned.

See Also

ADDITEM | DELETEWO | DELITEM
ENABLEWO | GETNUMBER | GETTEXT
SETFOCUS | SETNUMBER | SETTEXT
SHOWWO |  |

Windows object error codes

Standard Windows Object Flags


COMMGET

COMMGET ------------ Return the characteristics of a serial line

Type

U/BL command or statement

Syntax

COMMGET(chan,speed,pty,csize,nstp,flow,modem,dummy[,vmin,vtim])

Arguments

chan

A valid channel number opened using the OPEN statement, and must be associated with a character device, that is, any serial line.

speed

Returns the speed of the line.

pty

Returns the parity of the line. This argument is a bit mask where, if set to zero, parity generation and detection are disabled.

Bit 1 set = odd parity.

Bit 2 set = even parity.

Bit 3 set = input parity is enabled (otherwise input parity checking is disabled). This allows output parity generation without input parity errors.

csize

Returns the character size. Valid values include 5, 6, 7, and 8.

nstp

Returns the number of stop bits, either 1 or 2.

flow

Supported under UNIX only. Returns flow control. This argument is also a bit mask. If set to zero, flow control is disabled.

Bit 1 set = IXON is enabled.

Bit 2 set = IXOFF is enabled.

Bit 3 set = IXANY is enabled.

Bit 4 set = CTS protocol is enabled.

Bit 5 set = RTS signalling is enabled.

Under Windows the buffer size cannot be changed after the port is opened, and COMMGET returns a value -1 for its size.

modem

Supported under UNIX only. If set to zero, then the line is assumed to be a local, direct connection with no modem control. The Data-Terminal-Ready (DTR) and Request-To-Send (RTS) are asserted, but incoming modem signals are ignored. If set to 1, modem control is assumed. This means the DTR and RTS are asserted. Also, the Carrier-Detect (CD) signal must be returned before communication can proceed.

dummy

No longer used. Recieves a value of -1.

vmin

Represents the minimum number of characters that should be received when the read is satisfied, that is, the characters are returned to the user.

vtim

A timer of 0.10 second granularity used to time-out bursty and short-term data transmissions.

Description

The COMMGET command is used to return the current values of a serial line's characteristics. The COMMSET command is used to set the line's characteristics.

Note: U/BL is not case sensitive with regard to the device name.

On Windows based platforms, if an COMMxxxxx command is attempted on any file other than a Windows COMx port, for example, "COM1" or "COM2", then error 9404 - 'Channel is not associated with a character device' - is generated. On UNIX based platforms the same error will be generated if an attempt is made to use an COMMxxxxx statement on a non-character device, for example, something other that a /dev/tty.... line.

On Windows so that U/BL can access the serial port without invoking BBSPOOL (if used), the port's name must be preceded with an "!". When using any of the COMMxxxxx statements, always OPEN the port like this:

OPEN FILE[chan,mode],"!COMn"

where chan is a numeric expression for the channel number you want the port to be OPENed on, mode is a numeric expression for the file OPEN mode you wish to use and n is either 1 or 2 depending on the serial port being accessed.

Example

Interrogate a line with characteristics of 1200 baud with no parity, 8 data bits, 1 stop bit, IXON IXANY, and no modem control:

* list

LET CHAN=0

IF AND(SYS(30),56636) THEN

OPEN FILE[0,5],"/dev/tty01"

ELSE

OPEN FILE[0,5],"COM1"

ENDIF

COMMGET(CHAN,BAUD,PTY,CSIZE,NSTP,FLOW,MODEM,0)

PRINT "Device OPEN on channel ";CHAN;" has the characteristics:"

PRINT "Baud Rate: ";BAUD

PRINT "Parity: ";PTY

PRINT "Character Size: ";CSIZE

PRINT "Number of Stop Bits: ";NSTP

IF AND(SYS(30),56636) THEN

PRINT "Flow Control (Bit mask): ";FLOW

ENDIF

PRINT "Modem Control: ";MODEM

* run

Device OPEN on channel 0 has the characteristics:

Baud Rate: 1200

Parity: 0

Character Size: 8

Number of Stop Bits: 1

Flow Control (Bit mask): 5

Modem Control: 0

See also

COMMSET


COMMIT

COMMIT ---------- Accept a set of SQL operations

Type

SQL Access command

Syntax

COMMIT([CONN$][,STAT])

Arguments

CONN$ | The connection identifier. This argument is optional, it is only required in programs that use multiple concurrent connections. If this argument is specified and the connection exists transactions will be committed for the specified connection. If the connection identifier is specified and that connection does not exist then an error status of 2 is returned. If the connection identifier is not specified then transactions will be committed for the current connection.
STAT | Status return which receives the status of committing the transaction. A status of 0 is returned for successful completion. A status return of -1 indicates a failure committing the transaction, if this occurs use the SQLERR statement to determine the exact nature of the error.

Description

The COMMIT statement accepts the previous set of SQL operations, applying their changes to the target data files. The group of SQL operations applied, referred to as a transaction, is the collection of queries run (via the EXEC statement) since the last transactional control statement (one of the COMMIT; ROLLBACK or LOGON statements) was called. A transaction is not limited to one SQL Access cursor, a transaction is regarded as the effect of all of the EXEC statements invoked since the last transactional control statement.

The COMMIT statement is only supported when using datasources which support transactional processing. For datasources which have no transactional support, the COMMIT statement does nothing as the effect of each EXEC statement is immediately consigned to disk.

Example

@AddProd REM Subroutine to add a new product to the catalogue

REM

REM Uses service queries ADD_PROD and ADD_PRICING with

REM product details and pricing passed in DETAILS$ and CHARGE$

EXEC "ADD_PROD", DETAILS$, ER

IF ER=0 THEN

EXEC "ADD_PRICING", CHARGE$, ER

IF ER<>0 THEN

ROLLBACK (ER) : Cannot add pricing so don't add product

IF ER<>0 THEN GOSUB @SeriousError

ELSE

COMMIT (ER) : Update database

IF ER=0 THEN RETURN

END IF

END IF

REM Only reach here under error conditions

GOSUB @AddError

RETURN

See also

EXEC

LOGON

ROLLBACK


COMMREAD

Type

U/BL command or statement

Syntax

COMMREAD(chan,buf$,nbytes)

Arguments

chan | A channel associated with a serial device.
buf$ | The string to receive incoming data.
nbytes | Returns the number of bytes actually read.

Description

The COMMREAD statement reads from a serial device, for example, a COM port on Windows platforms. The advantage of the COMMREAD statement over the INPUT FILE statement is that no translation is performed on any of the input characters. This statement can be used with the COMMGET (get line characteristics) and COMMSET (set line characteristics) statements.

So that U/BL can access the serial port without invoking BBSPOOL (if used), the port's name must be preceded with an "!". When using any of the COMMxxxxx statements, always OPEN the port like this:

OPEN FILE[chan,mode],"!COMn"

where chan is a numeric expression for the channel number you want the port to be OPENed on, mode is a numeric expression for the file OPEN mode you wish to use and n is either 1 or 2 depending on the serial port being accessed. Note that U/BL is not case sensitive with regard to the device name.

On Windows platforms, if an COMMxxxxx command is attempted on any file other than "COM1" or "COM2", then error 9404 - 'Channel is not associated with a character device' - is generated. On UNIX based platforms the same error is generated if an attempt is made to use an COMMxxxxx statement on a non-character device, for example, something other that a /dev/tty.... line.

Note: 'Console' input Channel 16 is not a serial line under Windows versions of U/BL. Therefore an implicit COMMREAD on channel 16 does not work.

See also

COMMWRITE


COMMSET

COMMSET ----------- Set or change the values of a serial line's characteristics

Type

U/BL command or statement

Syntax

COMMSET(chan,speed,pty,csize,nstp,flow,modem,dummy[,vmin,vtim])

Arguments

chan

A valid channel number opened using the OPEN statement, and must be associated with a character device, that is, any serial line.

speed

Sets the speed of the line. Valid values include 9600, 4800, 2400, 1200, 600, 300, 200, 150 and 110 baud. On Unix based platforms baud rates of 19200 and 38400 are also supported. Check your hardware manual for supported values.

pty

Sets the parity of the line. This argument is a bit mask where, if set to zero, parity generation and detection are disabled.

Bit 1 set = odd parity.

Bit 2 set = even parity.

Bit 3 set = input parity is enabled (otherwise input parity checking is disabled). This allows output parity generation without input parity errors.

csize

Sets the character size. Valid values include 5, 6, 7, and 8.

nstp

Sets the number of stop bits, either 1 or 2.

flow

Sets flow control. This argument is also a bit mask. If set to zero, flow control is disabled.

Bit 1 set = IXON is enabled.

Bit 2 set = IXOFF is enabled.

Bit 3 set = IXANY is enabled.

Bit 4 set = CTS protocol is enabled.

Bit 5 set = RTS signalling is enabled.

Under Windows IXON and IXOFF cannot be individually specified. Enabling one automatically enables the other. Also under Windows IXANY is not supported.

modem

Supported under UNIX only. If set to zero, then the line is assumed to be a local, direct connection with no modem control. The Data-Terminal-Ready (DTR) and Request-To-Send (RTS) are asserted, but incoming modem signals are ignored. If set to 1, modem control is assumed. This means the DTR and RTS are asserted. Also, the Carrier-Detect (CD) signal must be returned before communication can proceed.

dummy

Not supported.

vmin

Represents the minimum number of characters that should be received when the read is satisfied, that is,. the characters are returned to the user.

vtim

A timer of 0.10 second granularity used to time-out bursty and short-term data transmissions.

Description

The COMMSET command is used to set or change the values of a serial line's characteristics. The COMMGET command is used to interrogate the line's characteristics.

On Windows platforms, if an COMMxxxxx statement is attempted on any file other than a Windows COMx port, for example, "COM1" or "COM2", then error 9404 - 'Channel is not associated with a character device' - will be generated. On UNIX based platforms the same error will be generated if an attempt is made to use an COMMxxxxx statement on a non-character device, for example, something other that a /dev/tty.... line.

The four possible values for the two line control directives vmin and vtim, and their interactions are:

vmin > 0, vtim > 0

In this case, vtim serves as an inter-character timer activated after the first character is received, and reset upon receipt of each character. vmin and vtim interact as follows:

  • As soon as one character is received the inter-character timer is started.

  • If vmin characters are received before the inter-character timer expires, the read is satisfied.

  • If the timer expires before vmin characters are received, the characters received to that point are returned to the user.

  • A read operation will sleep until the vmin and vtim mechanisms are activated by the receipt of the first character; thus, at least one character must be returned.

vmin > 0, vtim = 0

In this case, because vtim=0, the timer plays no role and only vmin is significant. A read operation is not satisfied until vmin characters are received.

vmin = 0, vtim > 0

In this case, because vmin=0, vtim no longer serves as an inter-character timer, but now serves as a read timer that is activated as soon as the read operation is processed. A read operation is satisfied as soon as a single character is received or the timer expires, in which case, the read operation will not return any characters.

vmin = 0, vtim = 0

In this case, return is immediate. If characters are present, they will be returned to the user.

Under Windows, so that U/BL can access the serial port without invoking BBSPOOL (if used), the port's name must be preceded with an "!". When using any of the COMMxxxxx statements, always OPEN the port like this:

OPEN FILE[chan,mode],"!COMn"

where chan is a numeric expression for the channel number you want the port to be OPENed on, mode is a numeric expression for the file OPEN mode you wish to use and n is either 1 or 2 depending on the serial port being accessed. Note that U/BL is not case sensitive with regard to the device name.

Example

To set a line to 1200 baud with no parity, 8 data bits, 1 stop bit, IXON IXANY, and no modem control:

* list

LET CHAN=0

IF AND(SYS(30),65536)

OPEN FILE[0,5],"/dev/tty01"

ELSE

OPEN FILE[0,5],"!COM1"

ENDIF

COMMSET(CHAN,1200,0,8,1,5,0,0)

See also

BBSPOOL

COMMGET


COMMWRITE

Type

U/BL command or statement

Syntax

COMMWRITE(chan,buf$,nbytes)

Arguments

chan | A channel associated with a serial device.
buf$ | The string to be written. The number of bytes written depends on the current length of buf$.
nbytes | Returns the number of bytes actually written.

Description

The COMMWRITE statement writes to a serial device, for example, a COM port on Windows platforms. The advantage of the COMMWRITE statement over PRINT FILE is that no translation is performed on any of the output characters. This statement can be used with COMMGET (get line characteristics) and COMMSET (set line characteristics).

So that U/BL can access the serial port without invoking BBSPOOL (if used), the port's name must be preceded with an "!". When using any of the COMMxxxxx statements, always OPEN the port like this:

OPEN FILE[chan,mode],"!COMn"

where chan is a numeric expression for the channel number you want the port to be OPENed on, mode is a numeric expression for the file OPEN mode you wish to use and n is either 1 or 2 depending on the serial port being accessed. Note that U/BL is not case sensitive with regard to the device name.

On Windows based platforms, if an COMMxxxxx command is attempted on any file other than "COM1" or "COM2", then:

error 9404 - 'Channel is not associated with a character device'

is generated. On UNIX based platforms the same error will be generated if an attempt is made to use an COMMxxxxx statement on a non-character device, for example, something other that a /dev/tty.... line).

See also

COMMREAD


CON

CON ---------- Resumes a program after a stop or interruption

Type

U/BL command

Syntax

CON

Description

The CON command resumes the execution of a program at the line after the point at which the program STOPped. The values of variables and the status of files remain unchanged. The CON command is used during testing and debugging of a program. Typically, STOP statements are inserted at strategic points and variables can be tested or changed, or the program can be edited, before CONtinuing with the execution.

RUN line_no has the same effect as CON when line_no references the first statement after the point at which the program STOPped.

Example

* list

00010 FOR I=1 TO 2

00020 LET TOTAL=TOTAL+1

00030 STOP

00040 NEXT I

* run

STOP at 30

* ;total

1

* con

STOP at 30

* 50 ;total

* CON

3 2

See also

RUN


CONTROL

CONTROL ---------- Allows control codes to be inputted

Type

U/BL statement.

Syntax

CONTROL

Description

The CONTROL statement allows the INPUT and INPUT USING statements to read control characters (those less than ASCII 32) from the keyboard.

The CONTROL statement is equivalent to the STMA 6,2 statement and is only supported when U/BL is emulating SuperDOS Business BASIC (that is, when BBEXTENSION=SDOS).

Example

See STMA 5 & 6 & 7

See also

INPUT

INPUT USING

NOCONTROL


CONVERT

CONVERT ---------- Translates a string of characters

Type

U/BL Statement.

Syntax

CONVERT string,table

Arguments

string | A string variable, containing the characters to be translated
table | A string variable or literal, containing a translation table.

Description

The CONVERT statement translates a string of characters, according to a user-defined table.

The ASCII value of each character in the string parameter is used to find the position of the table which replaces it. If the table is shorter than the ASCII value of the character, the last character in the table is used.

The CONVERT statement is equivalent to the STMA 13 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program converts a user supplied string. All upper case is converted to lower case and the lower case is converted to upper case.

10 DIM TTAB$ (255) ,X$ (100)

20 FOR I=0 TO 122

X=I

IF I>=65 & I<=90 THEN X=I+32

IF I>=97 THEN X=I-32

TTAB$ (0) =CHR$ (X) : INITIALIZE TRANSLATION TABLE

NEXT I

30 LOWERC : ALLOW LOWER CASE ON INPUT

40 INPUT USING " " ,"ENTER A STRING TO BE TRANSLATED " ,X$

50 CONVERT X$ ,TTAB$ : PERFORM THE TRANSLATION

60 PRINT "THE TRANSLATED STRING IS: " ;X$

70 END

See also

STMA 13

STMA 14


CREATE

CREATE ---------- Creates a disk file of the specified type and size

Type

U/BL Statement.

Syntax

CREATE file$,fcblock$,type$,recsize,maxrec

CREATE file$,fcblock$,type$,recsize,maxrec[,extent size]

Arguments

file$ | A string variable or literal containing the file specification
fcblock$ | A work string for the FCB, dimensioned to at least 80 bytes
type$ | A string variable or literal containing the file type
recsize | A numeric expresion containing the record size, or key size if the file is an index
maxrec | A numeric expression containing the number of records in the file (if a type D file) or the number of sectors in the file (all other file types)
extent size | An optional numeric expression specifying the number of sectors per extent (minimum of two sectors)

Description

The CREATE statement creates a disk file based on the arguments specified. If the file specification does not specify a drive and user group, it uses the default values. If the file already exists, #ERR is set to 2.

If you specify the extent size argument, and it is non-zero, the file is an extendable file. This means that a file automatically extends itself by the specified number of sectors whenever more space is needed for the file, to a maximum of up to 100 extends.

The table below lists the valid file types and their associated parameters:

Type | Description | Min-Max Rec size | Min-Max #Records
D | SuperDOS linked data file DG-type linked data file Non-linked data file | 5-65535 14-65535 1-65535 | 1-16777215 1-16777215 1-16777215
I | Index with no duplicate keys | 1-252 | 1-16777215
J | Index with duplicate keys | 1-252 | 1-16777215
T | Text file | 512 | 1-16777215
R | Relocatable binary file | 512 | 1-16777215
U | User-defined file keys | 1-65535 | 1-16777215

Possible Errors:

The following cases may generate SuperDOS error #80 (Invalid parameters in a system call):

  • When you attempt ito create an index file whose specified key size is not in the range of 1 to 252

  • When the file type is invalid

  • When the extent size is invalid.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

The following program demonstrates the use of the CREATE and DELETE statements. The user specified a text file and this program creates a temporary file, copies the entire file and replaces all carriage return and line feed.

This program uses INPUT FILE to read the file and PRINT FILE to output to the new file. A much faster method is to use the READ FILE and WRITE FILE or BLOCK READ FILE and BLOCK WRITE FILE statements. However, it is most efficient to use the INPUT and PRINT statements, as these use fewer lines of code.

10 DIM LINE$ (1024) ,FILNAM$ (20)

20 INPUT USING " ", "ENTER NAME OR FILE TO COPY" ,FILNAM$

25 OPEN FILE (0, 5) ,FILNAM$

30 #ERRJMP OFF :Disable error logic

  CREATE "TEXT.TMP" ,LINES, "T" ,512,30,20 :Create file, type "T"

  :30 sectors, with 20 sector extends

40 #ERRJMP ON :Enable error logic

  IF #ERR THEN

50 DELETE "TEXT.TMP" :Delete if it exists

60 GOTO 30

  END IF

70 OPEN FILE (1,6), "TEXT.TMP" :Open temp file

80 INPUT FILE (0) ,USING " " , LINE$ :Input a line

90 PRINT FILE (1) , LINE$ :Output line with cr/lf

100 IF EOF (0) =0 THEN GOTO 80

110 CLOSE

120 END


CRM$

CRM$ ---------- Returns a compressed string

Type

U/BL function

Syntax

target$=CRM$(source$)

Arguments

target$ | A string variable which receives the compressed string.
source$ | A string expression to be compressed.

Description

The CRM$ function crams every three bytes of a source string into two bytes of a target string. Only the uppercase letters (A-Z), the numbers (0-9) and four other characters will be crammed. The four other characters are set by the STMA 10 statement, and their current setting can be determined by the STMA 9,7 statement. The default values for these special characters under Data General and B32 emulations are:

' ' | (space)
',' | (comma)
'-' | (hyphen)
'.' | (period)

The default values for these special characters under SDOS emulations are:

' ' | (space)
'/' | (slash)
',' | (comma)
'.' | (period)

Any other character in the source string becomes a space (or whatever character redefines a space). The target string can be the same as the source string.

The UCM$ function uncompresses a string which has been compressed by CRM$.

A common use for CRM$ is in key strings for index files, where only upper case characters are used. Keyed statements run faster when shorter key strings are used, because more keys fit in each index level and fewer levels may have to be used, but this advantage must be balanced against the need to compress and uncompress the keys and the disadvantage of the limited character set allowed.

Example

* list

00010 DIM X$[3],Y$[2],Z$[3]

00015 X$="UBB"

00020 Y$=CRM$(X$)

00030 Z$=UCM$(Y$)

00040 PRINT Z$

* run

UBB

Therefore, y$=chr$(55015,2)

See also

PACK

STMA 9,7

STMA 10

UCM$


@DESC

@DESC ---------- Retrieve or modify the @INPUT environment

Type

U/BL Statement.

Syntax

@DESC (act,env$[,uptab$])

Arguments

act | A numeric expression specifying the action to be taken. It can be set to 0 to retrieve the environment information or 1 to set the environment information.
env$ | If act is set to 0, env$ receives the environment information. If act is set to 1, then the information in env$ is used to modify the environment information.
uptab$ | An optional string variable which defines the multi-sequence unpend and special keys. The string contains an entry for four unpend keys, six special keys and one delete key. If the environment variable BBATINPWAIT is set to Y, Basic will wait for any characters which may follow an ESC used in the unpend table.

Description

The @DESC statement retrieves or modifies the @INPUT environment. It is used in conjunction with the @INPUT and @PRINT statements.

To retrieve information set the act variable to 0. The retrieved information is placed in the env$ argument.

To replace the environment information with the value in the env$ argument set the act variable to 1.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The environment information is described in the table below:

Bytes

Information

1 - 2

Flags

Bits | Information
bit 0 | If set, @(-10,-1) returns a length of 0 when CR is pressed
bit 1 | If set, @INPUT does not blank rest of field when CR is entered as the first character.
bit 2 | If set, the alternate @ value is used when displaying a field that is to be @INPUT. If set, underlines are not displayed.
bit 3 | If set, assume terminal is using hidden attributes. This means that the start/end reverse video attribute does not use a space on the screen.
bit 4 | If set, multi-sequence unpends are allowed and must be specified in an unpend table.

3 - 3

Alternate @ value used at the beginning of a field when displaying it for @INPUT.

4 - 4

Alternate @ value used at the end of a field when displaying it for @INPUT.

5 - 5

The value of the backspace key. When the user enters this value during an @INPUT the backspace sequence takes place and deletes the character to the left of the cursor.

6 - 6

The value of the insert key. When the user enters this value during an @INPUT the characters in the field at the current location are shifted right one position and a space is inserted.

7 - 7

The value of the LEFT ARROW key. When the user enters this value, the cursor moves 1 place to the left. During an @ACTION statement, the LEFT ARROW key skips to the previous field.

8 - 8

The value of the RIGHT ARROW key. When the user enters this value, the cursor moves 1 place to the right. During an @ACTION statement, the RIGHT ARROW key skips to the next field.

9 - 9

The value of the delete key. When the user enters this value the character at the cursor is deleted. This is the inverse of the insert key.

10 - 10

The value of the erase-to-end-of-field key. During an @INPUT this key blanks the filed from the cursor to the end of the field.

When field is displayed for @INPUT, the alpha and crammed fields are appended with underlines so the user can know how large a field is. However, setting bit 2 of the flags field, results in the underlines not being output and the alternate @ values (which refer to the terminal control functions) being output before and after the field. The default alternate @ values are 44 and 45, so setting bit 2 results in the current @INPUT field being displayed in reverse video. Changing the alternate @ value gives a programmer the flexibility to customize the user interface in an @INPUT.

Certain terminals use a screen position for attributes, such as reverse video. Because of this @PRINT displays an extra space before each field to keep the field displays in the same place on the screen If your terminal does not use a screen position, flag bit 3 can be set and the extra space is not output.

When you are retrieving information (the action parameter is set to 0), the number of bytes retrieved is the minimum of the DIMension of the string variable and 10. The current length of the string is set to the number of bytes moved. When you are modifying information (the action parameter is set to 1), the number of bytes modified is the minimum of the DIMension of the string variable and 10.

Note: The first two bits of the flags value can be accessed band modified by the GETSYSBITS and SETSYSBITS statements respectively.

Example

:

00100 _@DESC (0,ENV$)

00110 LET FLAGS=ASC(ENV$[1,2]) \ FLAGS=OR(FLAGS,4)

00120 LET ENV$[1,2]=CHR$(FLAGS,2)

00130 _@DESC (1,ENV$)

:

See also

BBATINPWAIT

@INPUT

@PRINT


@DIM

@DIM --------- Sets aside enough space for the specified number of field specs

Type

U/BL Statement.

Syntax

@DIM(flds)

Arguments

flds

A numeric expression specifying the maximum number of fields that can be used in @INPUT, @PRINT, @SET, and so on.

Description

The @DIM statement sets aside enough space for the specified number of field specs. The field specs are required in all the @ statements such as @PRINT, @INPUT, @GET, and so on. The field specs are set by @SET, @SETFD, and @SETSD. Each field spec requires 10 bytes.

This statement can only be executed once in a program. If an attempt to execute another @DIM is made, it is ignored.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

00010 @DIM(10)


@DISPSUB

@DISPSUB ---------- Sets the line number of the custom display routine

Type

U/BL Statement.

Syntax

@DISPSUB(flag,lno)

Arguments

flag | A numeric expression that will be set to 0 if setting the line number of the custom display routine, or set to 1 if setting the line number to 0.
lno | A numeric expression specifying the first line number of the custom display routine used by @PRINT and @INPUT statements. Should be set to 0 if flag is set to 1.

Description

The @DISPSUB statement sets the line number of a custom display routine to be used by the @PRINT and/or @INPUT statements.

If a field being processed by an @INPUT or @PRINT has bit 1 of the flag bytes set, control is passed automatically to the subroutine specified by the line number in @DISPSUB. When an @INPUT is performed for a field whose @DISPSUB bit is set, the display subroutine is called twice for the field:

  • once prior to entry of the field.

  • once after entry of the field (as well as after any @EDITSUB).

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

:

00185 @DISPSUB (0,300)

:

00310 @DISPSUB (1,0)

:

See also

@EDITSUB


$D

$D ---------- Create a report file for the current state of U/BL

Type

U/BL command or statement.

Syntax

$D

Description

The $D command dumps the same contents as the $P command to a disk file <prog>.brk, where <prog> is the U/BL program SAVE name. If such a '.brk' file already exists then the details of the current dump will be appended. The '.brk' file is created in the current working data directory.

Example

UBL Debug Report - Mon Dec 22 14:04:24 1999

UBL Build date 22-Dec-99

UBL Environment Variables:

BBSIGNON=\USER\UBL\YOURBAN.BAN

BBTERM=\USER\UBL\COLOR.TDF

BBSOURCE=\USER\BBSOURCE

BBPROGS=\USER\BBPROGS

BBROOT=\USER\DATA

BBLINK=\USER\DATA\LINKS

BBERM=\USER\UBL\BASIC.ER

BBTMP=\TMP

BBSWAP=\TMP\SWAP

BBSPOOL=\USER\UBL\SPOOL.BAT

BBDEBUG=Y

Current Directory: \USER\DATA

Program: TESTPROG

Line No: 01000

On IKEY: Not defined

On ERROR: Not defined

Last Error: ERROR -10 - File Not Found: NEWFILE at line 01000

FOR/NEXT stack:

Index var: C Begins @ 00050 Step: 4 Value: 4

Index var: B Begins @ 00030 Step: 5 Value: 2

Index var: A Begins @ 00020 Step: 1 Value: 1

GOSUB/RETURN stack: 00060 00110

Open Channels:

Chan Mode Gpos Name................

0 5 512 :FILE1

1 5 124 :FILE2

Numeric Variables:

A LN% 6

B 2 PTR 0

C 4

CHAIN% 3

Strings:

X1$ 255 256 X2$ 0 0 X3$ 0 0

REC$ 0 0

String Content:

X1$

1 0102 0304 0506 0708 090a 0b0c 0d0e 0f10 ................

17 1112 1314 1516 1718 191a 1b1c 1d1e 1f20 ................

33 2122 2324 2526 2728 292a 2b2c 2d2e 2f30 !"#$%&'()*+,-./0

49 3132 3334 3536 3738 393a 3b3c 3d3e 3f40 123456789:;<=>?@

65 4142 4344 4546 4748 494a 4b4c 4d4e 4f50 ABCDEFGHIJKLMNOP

81 5152 5354 5556 5758 595a 5b5c 5d5e 5f60 QRSTUVWXYZ[\]^_`

97 6162 6364 6566 6768 696a 6b6c 6d6e 6f70 abcdefghijklmnop

113 7172 7374 7576 7778 797a 7b7c 7d7e 7f80 qrstuvwxyz{}~..

129 8182 8384 8586 8788 898a 8b8c 8d8e 8f90 ................

145 9192 9394 9596 9798 999a 9b9c 9d9e 9fa0 ................

161 a1a2 a3a4 a5a6 a7a8 a9aa abac adae afb0 ................

177 b1b2 b3b4 b5b6 b7b8 b9ba bbbc bdbe bfc0 ................

193 c1c2 c3c4 c5c6 c7c8 c9ca cbcc cdce cfd0 ................

209 d1d2 d3d4 d5d6 d7d8 d9da dbdc ddde dfe0 ................

225 e1e2 e3e4 e5e6 e7e8 e9ea ebec edee eff0 ................

241 f1f2 f3f4 f5f6 f7f8 f9fa fbfc fdfe ff ...............

Program Size:

Press any key for size display.

See also

$P


$DATE$

$DATE$ ---------- Converts a numerical date to a string suitable for output

Type

U/BL string function.

Syntax

date$=$DATE$(date[,date_in[,date_out]])

Arguments

date$ | A string variable which receives the date in the specified display format.
date | A numeric expression representing the date.
date_in | A numeric expression representing the format of the date argument. This is an optional argument; if not specified then it defaults to the value set by $SET_VALUE(DATE_IN,expr).
date_out | A numeric expression representing the format in which the resulting string will be returned. This argument is optional; if not specified then it defaults to the value set by $SET_VALUE(DATE_OUT,expr).

Description

The $DATE$ string function converts a numerical date into a string, using the selected string format. It is the opposite of the $VDATE command. The available string formats are:

Value | Format
0 | MM/DD/YY
1 | DD/MM/YY
2 | YY/MM/DD
3 | DD-Mmm-YY
4 | Mmm DD/YY
5 | DDMMYY
6 | MMDDYY
7 | YYMMDD
8 | YY-MM-DD
2000 | MM/DD/[[Y]Y]YY
2001 | DD/MM/[[Y]Y]YY
2002 | [[Y]Y]YY/MM/DD
2003 | DD-Mmm-[[Y]Y]YY
2004 | Mmm DD/[[Y]Y]YY
2005 | DDMMCC[[Y]Y]
2006 | MMDDCC[[Y]Y]
2007 | [[Y]Y]YYMMDD
2008 | [[Y]Y]YY-MM-DD

where DD, MM and YY are 2 digit representations for the day, month and year extracted from the encoded numeric date, and [[Y]Y]YY is an optional 2, 3 or 4 digit year also extracted from the encoded information. Exactly how many digits that are displayed for the 200X formats depends on the encoding method (see below) and the date information being converted. For Julian dates, the year information will always be displayed as 4 digits when creating a 200X format date string.

For all the other encoding methods, the number of digits will match the number of digits supplied in the encoded date.

The format of the output string to be generated is controlled by the date_out optional parameter. If this is not specified then the default output format (specified by the system DATE_OUT setting) is used. It is only possible to explicitly specify the output format to use if the date_in parameter has been included in the statement.

The date_in parameter itself controls the decoding method used to extract the date information from date, it can select the following methods:

Method | Encoding
0 | Julian date
1 | [Y]Y]YY*65536 + MM*256 + DD
2 | [Y]Y]YY*10000 + MM*100 + DD
2001 | CC*16777216+YY*65536 + MM*256 + DD
2002 | CC*1000000+ YY*10000 + MM*100 + DD

If the date_in parameter is not specified, then the default internal format (specified by the system DATE_IN setting) is assumed. This also has the effect that the default output format (DATE_OUT) is also employed as it is not possible to specify a value for the date_out parameter without specifying the date_in parameter.

Example

* list

00010 DIM I$[10]

00020 FOR I=0 TO 4

00030 LET I$=$DATE$(7600,0,I)

00040 PRINT I$,

00050 NEXT I

*run

10/21/88 21/10/88 88/10/21 21-Oct-88 Oct 21/88

See also

STMA 11

STMA 12

$VDATE


$DEBUG

$DEBUG ----------- Allow access to the debug facilities

Type

U/BL command and statement.

Syntax

$DEBUG

Description

When the $DEBUG command is entered at the '*' prompt, a function key menu is displayed at the top of the screen, consisting of:

F1 FIND F2 VIEW F3 BREAK F4 WATCH F10 DBG OFF

where

F1 For finding occurrences of code

F2 For viewing screen pages of program code

F3 For setting Breaks (like STOPs but do not use line numbers)

F4 For setting variables to be watched

Taking these in turn:

i) F1 FIND provides a further function key menu:

F1 FIND F2 NEXT F3 PREVIOUS F4 CONTEXT F10 RETURN

F1 FIND requests:

Find What :

The variable to be found should be entered.

F2 NEXT finds the next occurrence.

F3 PREVIOUS finds the previous occurrence.

F4 CONTEXT displays the previous and next five lines of code.

F10 RETURN returns to the main debug function key menu.

FIND/NEXT/PREVIOUS primes the edit buffer with the found line in each case.

ii) F2 VIEW displays a further function key menu:

F1 PG UP F2 PG DOWN F3 AROUND F4 TOP F10 RETURN

F1 PG UP displays the next 'page' of source.

F2 PG DOWN displays the previous 'page' of source.

F3 AROUND enter a line number, press F3. A group of line either side of the entered line will be displayed.

F4 TOP a) displays first 'page' of source, b) enter line number then F4: displays 'page' following the line number.

F10 RETURN returns to the main debug function key menu.

iii) F3 BREAK displays a further function key menu:

F1 LIST BRKS F2 ADD BRK F3 DEL BRK F4 CLEAR ALL F10 RETURN

F1 LIST BRKS list all breaks. The listing of break points lists all of the currently active break points. There is no limit to the number of break points which can be set through the $DEBUG command.

F2 ADD BRK add a break. Simply enter the line number, and the program stops BEFORE the line is executed. A break point set from the $DEBUG command will be saved along with the program. The break point will be lost if the program line is overwritten.

F3 DEL BRK delete a break. Enter A to E.

F4 CLEAR ALL clears all breaks.

F10 RETURN returns to the main debug function key menu.

iv) F4 WATCH displays a further function key menu:

F1 LIST WTCH F2 ADD WTCH F3 DEL WTCH F4 DEL WTCH F10 RETURN

F1 LIST WTCH list all numeric variables being watched.

F2 ADD WTCH a) enter a variable name followed by pressing F2. The program stops each time the variable changes.

b) enter a variable with a value, for example, B=3 then F2. The program stops when this value is reached.

F3 DEL WTCH deletes a watched variable. Enter A to E.

F4 CLEAR ALL clears all watched variables.

F10 RETURN returns to the main debug function key menu.

v) F10 DBG OFF to switch of the debug facilities.

Note: The $L command affects break point setting. When $L is active, break points set from the $DEBUG command are based on physical line numbers, rather than program line numbers.


$DEQUEUE

$DEQUEUE ---------- Reads and removes a record from a queue file

Type

U/BL statement

Syntax

$DEQUEUE error,lfile_no,record$

Arguments

error | A numeric variable which receives an error code if the $DEQUEUE statement fails.
lfile_no | A numeric expression representing the logical file number of the queue file.
record$ | A string variable which receives the record removed from the queue.

Description

The $DEQUEUE statement reads and then deletes a record from a queue file. The $ENQUEUE statement is used to write records to a queue file. Any error in the $DEQUEUE statement produces an error code in the error variable, and the record is set to null. The queue file is automatically locked on operations made against it with U/BL automatically locking record 0 of the file.

Error 114 means that the queue is empty.

This statement is not supported if the BBEXTENSION environment variable is set to SDOS.

Example

The following example program continuously reads records from the queue:

00100 PRINT "QTEST4.BAS - Test Q logic"

00200 DIM B$[544],R$[32],LFTABL$[104]

00210 LFTABL$=FILL$(0)

00300 LOPEN FILE[1,B$],"MHQ"

00400 $DO_WHILE 1 : REPEAT FOREVER

00600 $DEQUEUE E,1,R$

00700 IF E THEN

00710 IF E<>114 THEN STOP

00720 PRINT "End of queue - wait for 2 secs, count = ";C

00730 DELAY 20

00740 ELSE

00750 C=C+1

00800 END IF

00900 $END_DO

See also

$ENQUEUE


$DO_WHILE

$DO_WHILE ---------- Defines a conditional loop

Type

U/BL statement

Syntax

Syntax 1: | $DO_WHILE expression
 | statements
 | $END_DO
Syntax 2: | DO WHILE expression
 | statements
 | LOOP
Syntax 3: | DO_WHILE expression
 | statements
 | END LOOP

Arguments

expression

A numerical or logical expression

Description

DO WHILE and $DO_WHILE are synonyms for the same statement, and LOOP is a synonym for $END_DO.

Syntax 1 is always supported. To use syntax 2 the environment variable BBEXTENSION must be set to SDOS or UBB. To use syntax 3 the environment variable BBEXTENSION must be set to UBB. U/BL code using these statements will be listed back as syntax 1 unless BBEXTENSION=SDOS in which case the code will be listed as syntax 2. If BBEXTENSION=UBB the code will be listed as syntax 3.

The statements between the DO WHILE and the LOOP are executed until the expression evaluates to a zero value (FALSE). Use the DO WHILE/LOOP statements to construct loops that terminate once a particular condition is reached. This statement assists in keeping programs structured.

In order to use this construct, the environment variable BBEXTENSION must be set to UBB. This feature has been made "switchable" in this way so that the words DO, WHILE, and LOOP can be used as variable names.

The $DO_WHILE and $END_DO statements are implementations of the B32 statements. However, from revisions of U/BL 3.10 and above, you do not have to set the environment variable BBEXTENSION to include B32 in order to use these statements.

Examples

This code segment repeatedly inputs a string until the user enters no data:

00020 DIM I$[10]

00030 $DO_WHILE I$=""

00040 INPUT I$

00050 GOSUB 09000 :Process Input

00060 $END_DO

The example would run identically if line 30 was replaced by:

00030 DO UNTIL I$<>""

See also

BBEXTENSION

$DO_UNTIL

$END_DO


DATA

DATA ---------- Supplies values for the READ statement

Type

U/BL statement

Syntax

DATA constant [,constant]...

Arguments

constant

A number or a quoted string

Description

The DATA statement is used in conjunction with the READ statement to provide values for variables.

DATA statements are not executed by U/BL and may be placed anywhere in the program. A DATA statement may contain as many constants as will fit on a line. Numeric and string constants may be freely mixed. Any number of DATA statements may appear in a program.

READ statements access the DATA statements in the order they appear in the program. The data contained therein may be thought of as one continuous list of items, regardless of how many items are on a line or where the lines are placed in the program. The variables used in READ statements (numeric or string) must be in accordance with the corresponding constants in DATA statements, or an error occurs. DATA statements can be reREAD by using the RESTORE statement.

Example

The following example program prints the days of the week.

* list

00010 DATA "Sunday","Monday","Tuesday","Wednesday"

00020 DATA "Thursday","Friday","Saturday"

00030 DIM X$[9]

00040 FOR I=1 TO 7

00050 READ X$

00060 PRINT X$

00070 NEXT I

*run

Sunday

Monday

Tuesday

Wednesday

Thursday

Friday

Saturday

See also

READ

RESTORE


DDEMESSAGE

DDEMESSAGE ---------- Allows U/Gi to communicate with other Windows applications

Type

Windows Object Command

Syntax

DDEMESSAGE (MESSAGE$, DIRECTION)

Arguments

MESSAGE$ | Receives or provides the transferred message
DIRECTION | Specifies the direction of the communication.

Description

The DDMESSAGE command allows U/Gi to exchange DDE messages with other Windows tasks. Dependant on the DIRECTION parameter, this command either enables the message string specified in the MESSAGE$ parameter, to receive the contents of U/Gi's incoming DDE buffer, or places the message held in the string into U/Gi's output DDE buffer. The DIRECTION parameter can be set to the following values:

Value | Description
0 | Retrieves (into MESSAGE$) and clears the contents of U/Gi's DDE incoming buffer. The U/Gi DDE buffer is accessed from other Windows tasks by doing a DDE poke to application "UGi", Topic "UBL", Item "String"
1 | Sets U/Gi's outgoing DDE buffer to the contents of MESSAGE$. Other Windows tasks can examine this buffer by a DDE request on application "UGi", Topic "UBL", Item "String".

Note: Only 255 characters can be transmitted. The rest of the data in the buffer will be lost.

For full details on DDE refer to your Windows documentation.


DEF FN

DEF FN ---------- Defines a custom function

Type

U/BL statement.

Syntax

DEF FNa(dummy)=expr

Arguments

a | A single letter which defines the function.
dummy | A numeric variable name which is substituted for by the argument when the function is used.
expr | A numeric expression, normally involving dummy.

Description

The DEF FN statement allows a user to define custom functions for use in the program. Any custom function must be declared before it is used. The dummy argument in the DEF FN statement is replaced by the argument used when the function is called. A DEF FN statement can refer to another FN so long as the function referred to has already been defined.

Only one-letter names are allowed for functions, thus limiting the maximum number of functions to 26.

Example

* list

00010 DEF FNS(X)=X*X

00020 DEF FNH(X)=FNS(X)/2

00030 FOR I=1 TO 5

00040 PRINT FNS(I);" ";FNH(I)

00050 NEXT I

* run

1 0

4 2

9 4

16 8

25 12


DELAY

DELAY ---------- Pauses program execution for a specified time

Type

U/BL statement

Syntax

DELAY num

Arguments

num

A numeric expression

Description

The DELAY statement pauses a program. The variable num represents the number of tenths of a second the program pauses for. The DELAY period is rounded down to the nearest second unless the period is in the range 1 to 9 where a DELAY of one second will be actioned. For example, DELAY 20 pauses a program for 2 seconds. There is no limit to the length of a DELAY. If the interrupt key is pressed during a DELAY statement, the DELAY ends and normal IKEY handling is invoked. At the end of a DELAY, the keyboard output buffer is flushed. The DELAY 0 statement can be used in place of STMA 8,5 to flush the output buffer.

Example

The following example program prints an error message and then pauses for 10 seconds.

* list

01000 REM print error message routine

01010 PRINT @(24,1);"<7>";X$

01020 DELAY 100

01030 RETURN

See also

STMA 8


DELCUR

DELCUR ---------- Deletes a cursor

Type

SQL Access Command

Syntax

DELCUR(CUR$)

Arguments

CUR$

The cursor to be deleted

Description

The DELCUR command deletes and frees a previously allocated cursor.

See Also

SQL


DELETE

DELETE ---------- Deletes a file

Type

U/BL statement

Syntax

DELETE [error],file$

Arguments

error | An optional numeric variable to receive an error code
file$ | A DIMensioned string, substring or string literal containing the name (and optionally the path) of the file that is to be deleted.

Description

The DELETE statement removes a file or directory from the disk in the same way as the UNIX rm command and the DOS DELETE command. However, the DELETE statement does not accept wildcard characters. If the file does not exist, or cannot be deleted, for example, the user doesn't have the appropriate access permissions, then an error code is returned in the error variable (if specified). If no error variable has been specified, a trappable error occurs.

Link files are resolved. Use the STMC 35 statement to delete link files without resolving them.

Example

1. Using an error variable.

* list

00010 DIM FILE$[20]

00020 LET FILE$="TESTFILE"

00030 OPEN FILE[0,0],FILE$

00040 CLOSE

00050 PRINT "CREATED"

00060 FOR I=1 TO 2

00070 DELETE ERROR,FILE$

00080 IF ERROR THEN PRINT "NOT ";

00090 PRINT "DELETED"

00100 NEXT I

* run

CREATED

DELETED

NOT DELETED

2. Without an error variable.

* list

00010 DIM FILE$[20]

00020 LET FILE$="TESTFILE"

00030 OPEN FILE[0,0],FILE$

00040 CLOSE

00050 PRINT "CREATED"

00060 FOR I=1 TO 2

00070 DELETE FILE$

00080 IF ERROR THEN PRINT "NOT ";

00090 PRINT "DELETED"

00100 NEXT I

* run

CREATED

DELETED

ERROR -10 - File does not exist At Line 70 In scratch

See also

STMC 35


DELETEWO

DELETEWO ---------- Deletes one or all Windows objects

Type

Windows Object Command

Syntax

DELETEWO(ID [, STAT])

Arguments

ID | The unique handle of the Windows object to delete. Specifying a handle of -1 will delete all Windows objects in the current U/BL Window
STAT | Optional status return

Description

The DELETEWO statement deletes an individual Windows object, or all of them.

Often in Windows you will require controls to be dynamically destroyed, perhaps when moving from one screen to another, or when you leave your application. The DELETEWO command will do this. To save time a single DELETEWO command with a value for the object handle 'ID' of -1 will delete all Windows objects in the current U/BL Window.

Applies to:

  • All Windows objects with a handle

  • Text boxes.

Example

The following example program creates three edit boxes and then deletes all of them.

REM *** Create the edit boxes ****

EDITBOX(1,5,5,1,40,"Name",0)

EDITBOX(2,7,5,1,40,"Address 1",0)

EDITBOX(3,8,5,1,40,"Address 2",0)

REM *** rest of program here ****

REM *** Clear up and return ****

DELETEWO(-1)

END

See Also

BUTTON

COMBOBOX

EDITBOX

ENABLEWO

LISTBOX

RADIOBUTTON

SETFOCUS

SHOWWO

TEXTBOX


DELITEM

DELITEM ---------- Deletes items from list-based Windows objects

Type

Windows Object Command

Syntax

DELITEM(ID, INDEX [, STAT])

Arguments

ID | The unique handle of the Windows object
INDEX | The position of the item to be deleted
STAT | Optional status return.

Description

Lists of items are usually stored in list boxes; combo boxes or their dropdown equivalents. It is often useful to be able to dynamically add or delete objects from these lists under program control. The DELITEM command removes an entry from a list or combo box, referring to the entry by its INDEX. The first element in a combo or list box is element number 0. INDEX effectively identifies items by the number of preceding items in the list. INDEX can be set to -1 to remove all the current entries in the listbox or combobox.

Note: If you have the Standard Windows Object Flags SORT style on a list box or combo box, the items may not appear in the list in the order they were put in.

Applies to:

  • Combo boxes

  • Dropdown combo boxes

  • List boxes

  • Dropdown lists.

Example

The following example program creates a combo box and then deletes the second item from it.

REM **** Create an initial combo box ****

COMBOBOX(1,5,5,5,20,"Initial Selection | Option 1 | Option 2",32)

REM *** Delete the SECOND item ****

DELITEM(1,1)

See Also

ADDITEM

COMBOBOX

LISTBOX


DELREC

DELREC ---------- Deletes a record from a logical file

Type

U/BL command and statement.

Syntax

DELREC filenum, recnum

Arguments

filenum | A numeric expression corresponding to the logical file number of an LOPENed L-type file.
recnum | A numeric expression corresponding to the record number of the record to be deleted.

Description

The DELREC command deletes records from a linked-available-record file and adds them to a deleted record chain. The GETREC command can then be used to reuse the space made available. The DELREC command does not affect any indexes for the file. The KDEL command must be used to delete index entries.

Record 0 of type-L logical files is reserved for U/BL to maintain details of the deleted record chain and next available records.

The DELREC command locks record 0 during its execution using the filename supplied in the original OPEN or LOPEN statement used to open the file. U/BL checks that the record being deleted is a valid data record and has not already been deleted. If this is the case, an error is generated. If the DELREC command is used with a record which is unused or already deleted, the deleted record chain will be corrupted.

The DELREC command sets the first two bytes of a deleted record to zero. Programs can check these bytes to ensure that a record has not already been deleted. Any index entries pointing to a record which is about to be deleted should be KDELed first, so that another user's program does not read the deleted record's number from the index and try to access it.

Refer to the environment variable BBDELREC for further information on the deleted record chain.

If you want the Linked Available Files control information to be stored in the files FCB area, and a separate record 0 control record to not be maintained, when using the DELREC statement, set the BBNEWRECZERO environment variable to 'N' .

Example

00135 REM Delete the record from the index

00140 KDEL 1,BUF$,CUSTKEY$,RECNO

00145 REM Delete the record from the data file

00150 DELREC 2,RECNO

00160 PRINT "Record deleted"

See also

BBDELREC

BBNEWERECZERO


DIM

DIM ----------- Dimensions string and array variables

Type

U/BL command and statement

Syntax

DIM var(subscripts) [,var(subscripts)]..

Arguments

var | Any legal variable name, either numeric or string.
subscripts | For numeric arrays, the subscripts argument consists of one to four numeric expressions separated by commas, representing the number of elements in each dimension. For string variables, the subscripts argument consists of a single numeric expression representing the maximum length of the string. For string arrays, the subscripts argument consists of a hash sign '#' followed by a numeric expression representing the number of strings in the array, and then a comma and a second numeric expression. The second expression represents the maximum length of each string in the array.

Description

The DIM command is used to declare string variables and arrays with more than eleven elements in a U/BL program.

Note: Numeric variables do not need to be declared in a U/BL program.

U/BL reserves memory for strings and arrays depending on the parameters to the DIM statement. To create a single dimensional numeric array, include one figure in brackets after its name. The number in the brackets in the DIM statement is the highest number element a program can address. Arrays start at element zero, therefore there is actually one more element in the array than the figure implies. For example:

00010 DIM A[10]

actually DIMensions an eleven element array.

To create a numeric array with two or more dimensions, include two or more figures in brackets after its name. For example:

00020 DIM B[20,10]

This creates a two dimensional numeric array with 21 rows and 11 columns. The following example illustrates how to initialize such an array:

00020 DIM B[20,10]

00030 FOR I=0 TO 20

00040 OR J=0 TO 10

00050 LET B[I,J]=0

00060 NEXT J

00070 NEXT I

Three and four dimensional numeric arrays may be used; however, arrays with more than four dimensions are not allowed.

Note: Three and four dimensional arrays cannot be passed to shared procedures. One-dimensioned and two-dimensioned numerics don't necessarily have to be dimensioned (only necessary if default 10 or 10,10 definitions are not suitable).

To create a string variable, use a "$" sign at the end of the variable name, and give the maximum length of the string in brackets.

One-dimensional arrays of strings are allowed. This is an extension to Data General's Business BASIC, and, as with numeric arrays, they begin with a zero element. The first number in a string array refers to the string element, and must always be preceded with a hash, while the second refers to the maximum length of each string. For example, the following one-dimensional string array is set up to hold the names of the months:

00010 DIM MTH$[#12,9]

00020 FOR I=1 TO 12

00030 READ MTH$[#I]

00040 NEXT I

01000 DATA "January","February","March","April"

01010 DATA "May","June","July","August"

01020 DATA "September","October","November","December"

To refer to an individual string in a string array, use stringname$[#i] where 'i' is a number or variable representing the string in the array. In the above example, a PRINT of MTH$[#3] would display March. Note that two dimensional string arrays are not allowed.

Note: For string arrays, if the environment variable BBEXTENSION is set to include SDOS, string arrays are only recognized if the environment variable BBSXTRA is also set in your environment. This is because SuperDOS Business BASIC allows the numeric variable #1. Setting BBSXTRA causes U/BL to no longer recognize the variable #1 (or any other variable beginning with a # and a number). Also, if BBEXTENSION is set to include SDOS, then if I=2 and #I=4, U/BL will see A$[#I] as A$[4] rather than A$[#2].

Once a variable has been DIMensioned, it can be reDIMensioned, but only if the change leaves it the same size or makes it smaller. The usual reason for reDIMensioning a variable is to change the subscripts of multi-dimensional numeric arrays.

Several strings or arrays can be DIMensioned in one line, and strings and numeric arrays can be freely mixed.

Example

00010 DIM DAYS[365] : DAYS HAS 366 ELEMENTS

00020 DIM DAYS2[11,30] : DAYS2 HAS 372 ELEMENTS

00030 DIM DAYS2[52,6] : DAYS2 HAS BEEN REDIMENSIONED WITH 371 ELEMENTS

00040 DIM TODAY$[9] : STRING TO HOLD WEEK DAY: MAX 9 CHARACTERS

00050 DIM MTH$[#12,9] : TABLE OF STRINGS TO HOLD THE MONTHS

00060 REM 13 elements have been DIMensioned, but element 0

00070 REM will not be used.

00080 DIM QUARK[3,15,4,9] : A 4 DIMENSIONAL ARRAY WITH 3200 ELEMENTS

The above variables could have been declared more concisely as follows:

00010 DIM DAYS[365],DAYS2[11,30],TODAY$[9],MTH$[#12,9],QUARK[3,15,4,9]

See also

BBREDIM

BBSXTRA


DIR

DIR ----------- Displays or changes the current directory

Type

U/BL command and statement

Syntax

DIR [dirname]

Arguments

dirname

Either a string expression containing the name (and, if necessary, path to) a subdirectory, or a null filled or empty string variable to receive the present directory name.

Description

The DIR command when used by itself displays the current directory name. The DIR command with an argument representing a directory changes to the directory specified. If the directory does not exist, an I/O error 10 "File does not exist" occurs. If the argument to DIR is a string variable with a null value, the current directory name is placed in the variable.

Even if DIR has been used to change to a different directory, logging out of U/BL will return the user to the directory from which U/BL was invoked.

Examples

* dir

:U:USR:UBL

* dir "^

* dir

:U:USR

*dir "not_there

File does not exist

* DIM x$[10]

* x$="BASIC"

* DIR x$

* DIR

:U:USR:BASIC

* x$=""

* DIR x$

* PRINT x$

:U:USR:BASIC


DO WHILE

See $DO_WHILE.


_DUP

DUP ---------- Duplicates the code in a range of line numbers into a new line number range

Type

U/BL command and statement.

Syntax

DUP

Description

The DUP command acts upon a SAVEd file in memory. It duplicates the code in a range of line numbers or between two line labels into a new location in the program. It prompts for:

Start line of range .............. :

End line of range ................ :

Enter location to insert after ... :

The duplicated code is created without line numbers. To duplicate un-numbered or partially numbered code ensure that U/BL is running in physical line mode (see the $L command) and specify the region of code using its physical line numbers.

See also

$L


@EDITSUB

@EDITSUB ---------- Sets the line number of the custom EDIT routine

Type

U/BL Statement.

Syntax

@EDITSUB mode, line_number

Arguments

mode | Set the mode parameter to 1 to switch this functionality ON, and to 0 to switch this functionality OFF.
line_number | The line number to set.

Description

The @EDITSUB statement sets the line number of a custom EDIT routine to be used by the @INPUT statement.

If a field being processed by the @INPUT statement has bit 0 of the flags byte set, then control is automatically passed to the subroutine specified by the line_number parameter in the @EDITSUB statement. When control is passed to the routine, the BASIC variable #FIELD is set to the field number being processed. The ASCII characters entered by the users are contained in #FIELD$. The length of #FIELD$ is set to the number of characters entered. #TLSK is set to 1 if the information was deemed invalid by the standard error logic.

The programmer has the responsibility of determining if the information is correct, in which case #TLSK is set to 0. If the information i incorrect then #TLSK is set to 1 and any appropriate error messages are displayed. If #TLSK is nonzero when control is passed back to @INPUT, the cursor is repositioned to the same field and the user must re-enter the information.

The @EDITSUB routine can only execute the @GET and @SET statements. When using these statements @EDITSUB can determine which fields are processed during the @INPUT. For example, if a field must be a payment (P) or receipt (R), after editing the filed for a correct response of "P" or "R", the remaining fields can be skipped by setting bit 2 of the flags byte. Changing the value of #FIELD also allows you to skip fields. This can be done by ensuring #FIELD is in the original range of field numbers as specified in the @INPUT statement.

If the mode parameter is et to OFF, then if a field is processed by an @INPUT or @PRINT statement with the custom display flag set (bit 1) and the custom display routine line number is zero, the run-time error (#ERR=88) is generated.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


$E

$E ------------ Disable the ON ERR trap

Type

U/BL command.

Syntax

$E

Description

The $E command disables the ON ERR trap. This is a toggle on/off command.

See also

ON ERR


$END_DO

$END_DO ---------- Defines the end of a conditional loop

Type

U/BL statement

Syntax

Syntax 1 | $DO_WHILE expression
 | block of statements
 | $END_DO
Syntax 2 | $DO_UNTIL expression
 | statements
 | $END_DO

Arguments

expression

A numerical or logical expression

Description

LOOP and $END_DO are synonyms for the same statement. They define the end of a conditional loop begun with $DO_WHILE, DO WHILE or $DO_UNTIL.

The $END_DO statement must always be the last statement of a $DO_WHILE loop; DOs and $END_DOs must always come in pairs. When the interpreter reaches the $END_DO statement, it branches back to the corresponding DO and tests the condition.

The $END_DO statement is always accepted but U/BL will not always list it back as such. If BBEXTENSION=SDOS then U/BL will list code ENTERed as $END_DO as END LOOP. If BBEXTENSION includes UBB then U/BL will list code ENTERed as $END_DO as LOOP.

See also

BBEXTENSION

$DO_UNTIL

$DO_WHILE


$ENQUEUE

$ENQUEUE ---------- Adds a record to the queue

Type

U/BL statement

Syntax

$ENQUEUE error,lfile,record$

Arguments

error | A numeric variable which receives an error code if the $ENQUEUE statement fails.
lfile | A numeric expression representing the logical file number of the queue file.
record$ | A string variable which receives the record added to the queue.

Description

The $ENQUEUE statement writes a record to a queue file, which is created using the NWLFU (the non windows version of the logical file utility) utility with a file type of "Q". No record numbers are associated with this file, as it operates on a First In First Out (FIFO) principal. The $DEQUEUE statement reads a record from the file (and deletes it).

An error adding the record produces an error code in the error variable.

This statement is not supported if BBEXTENSION=SDOS.

Example

00100 PRINT "QTEST3.BAS - Test Q logic"

00200 DIM B$[544],R$[32],LFTABL$[100]

00210 PID_10000=SYS(9)*10000 \ LFTABL$=FILL$(0)

00300 LOPEN FILE[1,B$],"MHQ"

00310 $DO_WHILE PASS<=20

00320 START=SYS(0) \ CPU_S=SYS(5)

00400 FOR I= 1 TO 1000

00500 R$=CHR$(0,4),PID_10000+I

00600 $ENQUEUE E,1,R$

00700 IF E THEN STOP

00800 NEXT I

00900 LET PASS=PASS+1 \ ELA=SYS(0)-START \ CPU=(SYS(5)-CPU_S+5)/10

00910 PRINT PASS,"Elapsed: ";ELA,"Cpu: ";CPU,1000/ELA,1000/CPU

00920 STMA 8,5 : Flush output buffer

00930 DELAY 200

01000 $END_DO

See also

$DEQUEUE


$EXECUTE

$EXECUTE ----------- Passes the specified command to the operating system for execution

Type

U/BL command and statement.

Syntax

$EXECUTE cmd$[,return$],er

Arguments

cmd$ | A string expression giving the operating system command to be executed. This string is limited to 512 characters.
return$ | An optional string which receives any output (from "stdout" descriptor) from the command denoted by cmd$. This string is limited to 512 characters.
er | A numeric variable that receives the exit status of the command.

Description

This $EXECUTE command passes the contents of cmd$ to the operating system for execution. The resultant status is returned, with 0 usually signifying success.

Note: On Windows the operating system command is run on the server machine.

The BBOSCALLS control file has been introduced to restrict the system calls that can be made from U/BL. This control file is defined by the BBOSCALLS environment variable , and is used to explicitly list those system calls that U/BL can or cannot run using the $EXECUTE command.

Operating system limitations prevent an automatic error return being generated when using the $EXECUTE command to execute a system call on U/BL under Windows 95,98 and Me.

The STME 19 statement performs the same functionality.

The behavior of this statement can be modified using the BBEXECRETURN environment variable.

Example

01010 REM $EXECUTE "DIR/W *.DAT",STAT

00500 REM $EXECUTE BACKUP$,STAT

00040 REM $EXECUTE "ls -l",RETURN$,STAT

01070 REM $EXECUTE "ubl < inputfile > outputfile &",STAT

The last example will execute a background task under UNIX.

See also

BBEXECRETURN

BBOSCALLS

STME 19


#ERRJMP

#ERRJMP ---------- Set the action to take when an error occurs in certain statements

Type

U/BL statement

Syntax

#ERRJMP (flag)

Arguments

flag

Either 1 to switch _#ERRJMP on, or 0 to switch it off.

Description

The #ERRJMP statement either sets or resets a flag indicating the action to take when an error occurs in certain Business BASIC statements. If the flag argument is set to 1 (#ERRJMP ON) when an error occurs the normal ON ERR logic is invoked, and the Business BASIC variable #ERR is set to the error number. If the flag argument is set to 0 (#ERRJMP OFF) when an error occurs, the normal ON ERR log ic is not invoked, but the #ERR variable is set to the error number and the program continues to the next statement.

Typically the #ERRJMP statement is set to OFF before a statement that might have an error, and set to ON immediately after the statement. This enables the program to examine #ERR (before executing any statements that effect #ERR) to determine if an error occurred and then take any needed action. #ERR is set to zero immediately before executing the statements to which #ERRJMP applies.

The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

:

00040 _#ERRJMP (0)

00050 DELETE "SDOS.DT"

00060 DELETE "SDOS.IX"

00070 DELETE "SDOS.JX"

00080 DELETE "SDOS.TX"

00090 DELETE "SDOS.UD"

00100 _#ERRJMP (1)

:


EDIT

EDIT ---------- Invoke an external editor with a listing of the current program

Type

U/BL command.

Syntax

EDIT

Description

Typing EDIT at the U/BL '*' prompt invokes an external editor with a listing of the program currently LOADed in memory. If the program listing is changed, then U/BL updates the LOADed program with the modified version when the user leaves the editor and returns to U/BL. By default U/BL invokes the vi editor on a UNIX based system and EDIT on a Windows based system. The relevant executable must be in the current directory or in a directory on the user's path.

You can specify an alternative editor by setting the BBEDIT environment variable to the full path of the editor's executable file. An editor employed must accept the name of the file to edit as its first and only argument when invoked Unless the editor is in the current directory, or in a directory in your path, then BBEDIT must include the full path name.

The EDIT command is really an underscore command, so if the environment variable BBNOUSCORE is set to N this command will have to be preceded with an underscore, that is, _EDIT.

When using U/BL with U/Gi in GUI ('-g' graphical) mode, you can select a client based editor when using the U/BL EDIT command. This is achieved by using the BBREMEDIT and BBREMEDITOR environment variables. To enable the remote editing functionality, set the BBREMEDIT environment variable to Y. If you then issue an EDIT command, U/BL will attempt to launch an editing session on the machine where the U/Gi client is running. To facilitate this, U/BL automatically transfers a copy of the current program to the client PC.

The value of the BBREMEDITOR environment variable is then used to determine the editing program (if BBREMEDITOR is not set, U/BL will attempt to use a remote copy of the program pointed to by the BBEDIT environment variable). Upon completion of the editing session, U/Gi will automatically transfer the updated source file back to the U/BL process which will then update the working storage in the usual manner.

Note: The BBREMEDIT environment variable is not applicable on Windows 2000, Windows NT and Windows 95/98/Me. The remote editor is always used and can be specified by either the BBEDIT or the BBREMEDITOR environment variables. If both are set, the BBREMEDITOR environment variable will take precedence.

If you are using Notepad on Windows, and Notepad finds the program too large to edit, it will offer to launch Wordpad. If this happens, U/BL is unable to support the change of process. The pathname of Wordpad or another alternative editor must be substituted for the value of BBEDIT (or BBREMEDITOR) and U/BL restarted before that particular program can be edited using the new editor.

Example

On UNIX based systems:

* new

* .n

> ;"this is the first line

> ;"this is the second line

>

* list

PRINT "this is the first line"

PRINT "this is the second line"

* edit: BBEDIT not set, so U/BL clears

: the screen and invokes vi

vi session:

-----------------------------------------------------

PRINT "this is the first line"

PRINT "this is the second line"

~

~

:

:

~

~

"/tmp/DAAa12960" 2 lines, 75 characters

-----------------------------------------------------

The source code for the program can now be edited using vi. If a third line is added to the above listing as follows:

-----------------------------------------------------

  PRINT "this is the first line"

  PRINT "this is the second line"

;"this is the third line

~

~

:

:

~

~

-----------------------------------------------------

when the user exits vi, U/BL performs an automatic NEW and ENTER so that a LIST command now displays the following:

* edit

* list

PRINT "this is the first line"

  PRINT "this is the second line"

  PRINT "this is the third line"

*

See also

BBEDIT

BBNOUSCORE

BBREMEDIT

BBREMEDITOR


EDITBOX

EDITBOX ---------- Creates an edit box

Type

Windows Object Command

Syntax

EDITBOX(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, MODE, [, STAT])

Arguments

ID | The unique handle used to identify the object
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT | The initial text to be displayed in the edit box.
MODE | Specifies how the statement (and subsequently, the object) will work.
STAT | Optional status return.

Description

The EDITBOX command declares and displays an edit box initially containing the text specified in the TEXT$ parameter. On return, the new version of this text is not returned in TEXT$, but is made available for collection by a subsequent GETTEXT command. When priming multi-line edit boxes, the DOS-format line separator of carriage-return; line-feed (the BBASIC string "<13><10>") must be used to indicate new lines. In a similar way, any returns that are input into the edit box will be stored in the same format when they are returned to the program, either via the GETTEXT command or as a message if using NOTIFYTEXT.

The size and location of the edit box is determined by the ROW, COL, HEIGHT and WIDTH parameters, while the MODE parameter controls the appearance and operation of the edit box. MODE can be set to a combination of any of the standard Windows objects flags or the following statement specific settings:

Value

Description

32

Text in the edit box cannot be edited.

64

Allows multiple lines to be edited. This feature also allows the recording of the ENTER and TAB keys unless HANDLEENTER or HANDLETAB are in use, as these take priority.

128

Specifies that a carriage return be inserted, when the user presses the ENTER key while entering text into a multiple-line edit control.

256

The edit box will return a message in the format @^ followed by the handle of the object on a kill focus.

512

Modifies the operation of the NOTIFYKILLFOCUS flag to return (into U/BL's input buffer) the actual text in the edit box rather than the ^@ message. Best used in conjunction with the ENABLEWO(ID, 2) statement and the HANDLEENTER or HANDLETAB flags which this setting also modifies.

When using this switch, bear in mind that the Business BASIC INPUT statement terminates its input on the first field separator (such as a comma) in the inputted data. As there is no method for restricting the characters typed in an edit box, Transoft suggests the use of the INPUT USING statement instead.

1024

This makes the ENTER key act as a special key. When used without NOTIFYTEXT (see above), this flag causes the Windows focus to move off of the edit box when ENTER is pressed. If NOTIFYTEXT is in use, the operation of this flag is modified so that focus is not lost on the key press but the contents of the edit box is immediately sent as a message back to U/BL. If this option is used, ENTER will never reach the edit box, if the user wishes to record an ENTER in his text, they will have to type CTRL-RETURN instead.

2048

This makes the TAB key act as a special key. When used without NOTIFYTEXT (see above), this flag causes the Windows focus to move off of the edit box when TAB is pressed. If NOTIFYTEXT is in use, the operation of this flag is modified so that focus is not lost on the key press but the contents of the edit box is immediately sent as a message back to U/BL. If this option is used, TAB will never reach the edit box, if the user wishes to record an TAB in his text, they will have to type CTRL-TAB instead.

4096

The edit box will scroll horizontally to enable more data to be entered than can be displayed.

8192

All text in the edit box is obscured so the object can act as a password entry box.

16384

Adds scroll bars to the editbox.

32768

All input to the editbox will be converted to upper case.

65536

All input to the editbox will be converted to lower case.

To set the MODE flag with more than one of the above flags, simply OR together the values of the flags you wish to use. For example, to create an edit box which is multi-line and part of the tab order, set MODE to '64 U 1' or '65'.

Once you have created an edit box, you can use SETNUMBER statements to highlight all or part of the text displayed in the Edit box. To select all of the text, call SETNUMBER with a VALUE of -1; partial selections can be made by setting VALUE to the sum of the location of the 1st character to highlight and 256 times the location of the last character. For example:

For an edit box containing the text: "Clear Highlighted clear" set VALUE to 7+(256*17) to highlight the word "highlighted"

To deselect the text held in an Edit box, call SETNUMBER with a VALUE of 0.

Example

REM Remove any existing Windows objects or U/BL windows

DELETEWO(-1)

WINIT (ER)

REM Define working storage

DIM NEWLINE$[1]

DIM MESSAGE$[10]

DIM NAME$[100],ADDRESS1$[100],ADDRESS2$[100],ADDRESS3$[100]

REM Declare the object unpend character as ASCII 10

LET NEWLINE$="<10>"

LET OBJUNPEND=5

SETGUIOPT(OBJUNPEND,NEWLINE$)

REM Draw the input window complete with edit boxes & buttons

REM Define the Windows objects' flags

REM Edit box specific flags

LET HANDLEENTER=1024

LET HANDLETAB=2048

REM Button specific flags

LET AUTOFOCUS=2048

LET NOTIFYCHANGE=512

REM Generic flags - apply to all Windows objects

LET TABSTOP=1

REM Draw and show window

WMAKE ("Input",7,23,13,34,7,ER)

WSHOW ("Input",ER)

REM Write labels on base window

PRINT @(-30);@(2,2);"Name";@(4,2);"Address"

REM Define the edit boxes as tab stops

LET MODE=HANDLETAB+TABSTOP

EDITBOX(1,2,10,1,20,"",MODE)

EDITBOX(2,4,10,1,20,"",MODE)

EDITBOX(3,5,10,1,20,"",MODE)

EDITBOX(4,6,10,1,20,"",MODE)

REM Limit NAME to 20 characters and ADDRESS lines to 40 characters each

SETLEN (1, 20)

SETLEN (2, 40)

SETLEN (3, 40)

SETLEN (4, 40)

REM Define the controlling buttons as tab stops which return

REM a message on selection and return focus to the U/BL base-panel

LET MODE=TABSTOP+NOTIFYCHANGE+AUTOFOCUS

BUTTON (5,8,6,2,8,"OK",MODE,ER,"")

BUTTON (6,8,19,2,8,"Cancel",MODE,ER,"")

REM Define and set the initial values for the edit boxes

LET NAME$="Mr D.Smith"

LET ADDRESS1$="20,Big Street"

LET ADDRESS2$="Sometown"

LET ADDRESS3$="ST2 1OU"

SETTEXT (1,NAME$)

SETTEXT(2,ADDRESS1$)

SETTEXT(3,ADDRESS2$)

SETTEXT(4,ADDRESS3$)

DIM LAST$[100]

REM Explicitly set the focus to the first edit box

SETFOCUS (1,STAT)

REM Switch off echo (to hide button messages)

STMA 6,0

REM Allow user to edit data and wait for a button press

$DO_WHILE MESSAGE$<>"@^5;" AND MESSAGE$<>"@^6;"

INPUT "",MESSAGE$

$END_DO

REM Process button press

IF MESSAGE$="@^5;" THEN

REM 'OK' button pressed, read name and address the user has entered

GETTEXT (1,NAME$)

GETTEXT(2,ADDRESS1$)

GETTEXT(3,ADDRESS2$)

GETTEXT(4,ADDRESS3$)

ELSE

REM Input rejected by user, nullify data

LET NAME$,ADDRESS1$,ADDRESS2$,ADDRESS3$=""

END IF

REM Restore echo; close down and destroy window/objects

STMA 7,0

DELETEWO(-1)

WHIDE ("Input",ER)

WDELETE ("Input",ER)

Running the above program produces the following results:

Click the Cancel button to return to the U/BL prompt.

See Also

DELETEWO

ENABLEWO

Error codes

GETTEXT

SETFOCUS

SETLEN

SETTEXT

Standard Windows object flags


ENABLEWO

ENABLEWO ---------- Enables or disables Windows objects

Type

Windows Object Command

Syntax

ENABLEWO(ID, STATE [, STAT])

Arguments

ID | The unique handle of the Windows object
STATE | Description
STAT | Optional status return

Description

The ENABLEWO statement enables or disables (grays out) Windows Objects.

When Windows objects are visible, but are not applicable at the present time, it is usual to disable them (gray them out) so the user cannot select the object. This could be because the form does not yet have enough data, for example, a customer address form before the customer name has been entered, or because the data type prevents a particular field from being entered, for example, a stock control system may require entry of dimensions for a large item but not for small items.

The ENABLEWO command can disable individual objects by setting the STATE parameter to 0 or enable them by setting the STATE parameter to 1. It can also disable all objects bar the one specified in the statement by setting the STATE parameter to 2. This exclusive mode, besides disabling all the other objects, enables the specified object if it is currently disabled and sets the focus to it.

Example

REM Remove any existing Windows objects or U/BL windows

DELETEWO(-1)

WINIT (ER)

REM **** Set the object unpend character to LF ****

DIM A$[1]

LET A$="<10>" \ OBJUNPEND=5

SETGUIOPT(OBJUNPEND, A$)

REM Set up the strings to receive the data

DIM NAME$[100],ADDRESS1$[100],ADDRESS2$[100]

REM *** Create the edit boxes using the following flags ****

LET HANDLEENTER=1024 : } { Pressing <ENTER> sends the contents of the

LET NOTIFYTEXT=512 : } { edit box as a message to U/BL

LET FLAGS=HANDLEENTER+NOTIFYTEXT

EDITBOX(1,5,5,1,40,"Name",FLAGS)

EDITBOX(2,7,5,1,40,"Address 1", FLAGS)

EDITBOX(3,8,5,1,40,"Address 2", FLAGS)

REM **** Enable only the Name field and get the text ****

ENABLEWO(1,2)

INPUT NAME$

REM * Enable the first address field only and get the data *

ENABLEWO(2,2)

INPUT ADDRESS1$

REM * Enable second address field only and get the data *

ENABLEWO(3,2)

INPUT ADDRESS2$

REM * Return focus to U/BL's basepanel & destroy the objects

SETFOCUS(-1)

DELETEWO(-1)

END

See Also

BUTTON

COMBOBOX

DELETEWO

EDITBOX

LISTBOX

RADIOBUTTON

SETFOCUS

SHOWWO


END

END ---------- Terminates a program

Type

U/BL statement

Syntax

END

Description

The END statement stops a program, leaving any open files and variables untouched. Unlike the STOP command, no message is printed. The END statement does not have to be the highest numbered statement in a program, but there is an implicit END statement after the highest numbered statement.

Example

* list

00010 PRINT "this is line 10"

00020 END

00030 PRINT "this is line 30"

* run

this is line 10

See also

STOP


ENTER

ENTER ---------- Reads a program source file into working storage

Type

U/BL command and statement

Syntax

ENTER filename

Arguments

filename

A string expression containing the name (and optionally the path) of the file containing program source code.

Description

The ENTER command reads a text file from disk, and attempts to parse each line as a U/BL source program in exactly the same way as a numbered line typed in at the keyboard. The text file may have been created with a text editor, or by LISTing a program. If a line label or line number from the text file matches the one of a statement already in memory, the line from the text file overwrites the one in memory, otherwise it is inserted between existing lines. To ENTER a program without merging, issue a NEW statement before the ENTER statement.

The ENTER command is analogous to compiling a program in non-interpreted languages. Any statements which are not recognized as valid U/BL statements when a program is ENTERed, whilst being reported as errors, will be preceded by a question mark '?' and preserved in the SAVE file.

If any line read from the text file has the same line number as an existing line, and the BBOVERWRITE environment variable is set to Y, U/BL warns that a line is being overwritten. If the BBOVERWRITE environment variable isn't set, or if it is set to "N", no warning appears, but the line is still overwritten.

If the BBSEQUENCE environment variable is set to "Y", then this environment variable will cause U/BL to report any line number sequence errors which it encounters whilst a program's source code is being ENTERed.

Example

* 10 print "This is program 1

* 20 stop

* list "test1.ls

* new

* 10 print "This is program 2

* 15 end

* list "test2.ls

* new

* enter "test1.ls

* list

00010 PRINT "This is program 1"

00020 STOP

* enter "test2.ls

% Line 10 being overwritten.

* list

00010 PRINT "This is program 2"

00015 END

00020 STOP

See also

BBOVERWRITE

BBSEQUENCE

BBVERBOSE

LOAD


ENTRY

ENTRY ---------- Declares the entry point to a shared procedure routine

Type

U/BL command and statement

Syntax

ENTRY(enam$,line,arg1,....,argn)

Arguments

enam$ | A string expression or literal containing the shared procedure's name.
line | The statement line number in the shared module where the procedure named by enam$ starts.
arg1-n | The formal parameter list.

Description

The ENTRY statement declares an entry point named enam$ (normally literal) at line number line with the given formal parameter list. A shared module can have up to 32 _ENTRY points. The shared procedure is then called from your program by its procedure name, that is, enam$ together with the formal parameters for that procedure. For example:

PROCEDURE_NAME(arg1,....,argn)

This statement calls a procedure named PROCEDURE_NAME with the given arguments. The argument types used must match those specified in the corresponding ENTRY statement in the shared library module. Up to 18 arguments can be specified for each ENTRY point.

Note: To use shared procedures you must either set the BBSHLIB environment variable (which defines the amount of shared procedure memory) or the BBSHLIBFILE environment variable which specifies a file containing the shared procedure information.

Example

This example declares a shared procedure name "UPDATE" at line 1000 with the parameters RECTYP, REC$, and STATUS.

00100 ENTRY ("UPDATE",1000,RECTYP,REC$,STATUS)

The line in the calling program would then be:

00200 UPDATE(CUST,CUST$,STATUS)

See also

BBSHLIB

BBSHLIBFILE

INSTALL

RETURN

SHARE

SRETURN

Shared Memory Procedures


EOF

EOF ---------- Checks for end of file

Type

U/BL function

Syntax

EOF (channel)

Arguments

channel

A numeric expression representing the channel number of an open file.

Description

The EOF function returns a TRUE value (1) when the end of a file is detected. It works with physical files on disk only, not logical files or tape files. The EOF function should be used after a READ FILE or INPUT FILE statement.

Example

* list

00010 DIM X$[80]

00020 OPEN FILE[1,5],"TEXTFILE"

00030 INPUT FILE[1],USING "",X$

00040 IF EOF(1) THEN GOTO 00070

00050 PRINT X$

00060 GOTO 00030

00070 CLOSE FILE[1]

00999 END

See also

INPUT FILE

READ FILE


ERASE

ERASE ---------- Deletes program statements

Type

U/BL command and statement

Syntax

ERASE start_line [,end_line]

Arguments

start_line | A numeric literal. If the end_line parameter is also specified, then the start_line parameter represents the block of lines to be deleted. It need not actually exist. If the end_line parameter is not specified, then the start_line parameter must refer to an actual line in the current program which is to be erased.
end_line | A numeric literal representing the end of the block of lines to be deleted. It need not be a line which actually exists in the program.

Description

The ERASE command is used as a keyboard command to delete unwanted program lines. When used as a command the word ERASE and the end_line parameter are both optional.

When used as a program statement the word ERASE and the end_line parameter are mandatory. The end_line parameter can be the same as the start_line parameter. The ERASE command is used in programs to delete blocks of lines so that new blocks can be ENTERed. U/BL allows much larger user programs than Data General's Business BASIC, therefore, this technique is unlikely to be used.

If no lines exist in the specified block, an error occurs.

Example

* list

00010 REM This program is going to get shorter

00020 REM

00030 REM

00040 REM

00050 REM

00060 END

* erase 20,50

* list

00010 REM This program is going to get shorter

00060 END

* 10

* list

00060 END

See also

DUP

RENUM

RNAM


ERM$

ERM$ ---------- Returns an error message to a string

Type

U/BL function

Syntax

LET str$=ERM$(err_code)

Arguments

str$ | A string variable which receives the error message. The longest error message is 64 bytes long.
err_code | A numeric expression. If positive, the err_code parameter represents the record number of the error message in the BASIC.ER file. If negative the err_code parameter represents an I/O error code. The last I/O error code can be obtained by using the SYS(7) statement.

Description

The ERM$ function returns the error message associated with an error code, and assigns it to a string.

Use the ERM$ function after trapping an error via the ON ERR error trap or in statement's error parameter.

The result of ERM$ need not be assigned to a string variable using a LET statement. It is possible to use statements such as PRINT ERM$(x) and IF ERM$(x)=....

Examples

* list

00005 DIM X$[64]

00010 LET X$=ERM$(-1)

00020 PRINT X$

00030 LET X$=ERM$(1)

00040 PRINT X$

* run

Illegal file name

Illegal character

* print erm$(-1)

Illegal file name

See also

AERM$

ON ERR


EXEC

EXEC ---------- Executes a cursor previously prepared with an SQL statement

Type

SQL Access Command

Syntax

EXEC (CUR$, IBUF$[, STAT[, NROWS]])

Arguments

CUR$

The name of a previously-generated SQL Access cursor

IBUF$

A buffer containing any input data required by the SQL query associated with the cursor

STAT

A numerical variable to receive a status return. STAT returns one of the following codes:

-1 | Indicates a datasource specific error, if this occurs the program should use the SQLERR statement to determine what that error is
0 | No error
1 | No such cursor
2 | Insufficient input data
other | Driver-specific error code

NROWS

A numeric variable to receive the number of rows affected by running the query.

Description

The EXEC statement executes a previously prepared (by the SQL statement) SQL Access cursor. Any input required by the SQL query (associated with the cursor) should be passed in the IBUF$ parameter. This input buffer must be formatted according to the specification defined in the original SQL statement, which created the SQL Access cursor.

The EXEC statement merely runs the SQL query associated with the SQL Access cursor, it does not retrieve the result set from the query. To retrieve the result set from the query, you must use the FETCH command to access each row of the query's output. For queries which update the target data files, the EXEC statement will either immediately update the files or add the pending output to the current transaction depending on whether the datasource supports transactional processing. For transactionally-enabled datasources, any changes to the data files is only applied once a subsequent COMMIT statement has been executed (or implied by the LOGOFF statement). If a ROLLBACK statement is called instead of a COMMIT, the output associated with the EXEC, and any other non-committed output, will be discarded.

Example

The following source code assumes that a cursor of the name GETPROD has previously been prepared and that a product code is passed as an input parameter.

00200 IBUF$=PRODNO$

00210 EXEC ("GETPROD",IBUF$,STAT)

00220 IF STAT<>0 THEN

00230 GOSUB @Process_SQL_Error

00240 END IF

See Also

FETCH

SQL

SQLERR


EXT_UNPEND

EXT_UNPEND ---------- Specifies a string of unpend sequences

Type

U/BL Statement.

Syntax

EXT_UNPEND err code, unpend string$, flag

Arguments

err code | A numeric variable into which is returned an error # or 0 if there is no error.
unpend string$ | A string variable that contains a list of unpend sequences.
flag | A numeric expression that specifies the default terminal type to assume.

Description

The EXT_UNPEND statement is used to specify a list of unpend sequences to be used by the INPUT statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

An unpend string is actually a table. There is one entry for every desired unpend key sequence. A key sequence consists of the characters sent by the terminal when a key is pressed. For instance, pressing the F1 key on a WYSE 60 sends three characters: binary 1, @, and carriage return. If the value of the flag is not 0, EXT_UNPEND automatically builds an unpend table in unpend string$ composed of function keys F1-F16. The only valid values for flag are as follows:

1 | Assume a system console
2 | Assume a WYSE 50
3 | Assume a WYSE 60

When using the automatic build feature, if DIM'd length of the string is not large enough to contain all 16 function key sequences, then as many sequences are put in as will fit. If there is not enough room for at least 1 entry, an error 85 is returned.

This differs somewhat from the automatic unpend build used by @DESC. @DESC requires the string to have room for 11 entries plus the overhead (40 bytes for type 1-3). See @DESC for the default unpend string that is built.

The table can also be built for other terminals. The format of the table is as follows:

Bytes | Information
1-1 | # of entries (n)
2-2 | # bytes per entry
3-4 | work area (can be anything)
5-x | dummy entry (should be initialized to 0's) unpend key sequence 1 unpend key sequence 2 : : : : unpend key sequence n

If the unpend table has a value of zero for the entry length or number of entries, an error 85 is returned. If the entry length is greater than 10, an error 85 is returned.

After EXT_UNPEND has been executed without an error, the EXT_UNPEND flag (see TURN_ON) is automatically set. When this flag is set, the INPUT statement will unpend whenever any of the key sequences defined in the table are input. The INPUT statement will also unpend if any of the four normal unpend keys are input.

When an unpend occurs for any reason, #UKEY is set and indicates which unpend was used. If the normal unpend character was input by the user, #UKEY is set to 1-4. If one of the extended unpend sequences was input, #UKEY is set to entry number of the table with the high bit set, for example, if table entry 1 were input, the value of #UKEY would be 129. If the standard 16 function keys were stored in the table as entries 1 through 16 and the user unpended with the F7 key, #UKEY would be set to 135 (7 + 128 for the high bit set or 87h).

If INPUT USING specifies the optional unpend string, using one of the normal unpend characters causes the actual unpend character to be stored in the unpend string. Using one of the extended unpend sequences causes the value stored in #UKEY to be stored in the unpend string. In either case, the unpend variable (#UKEY) is set as described in the previous paragraph.

Other than setting #UKEY to a number with the high bit set, and storing the value of #UKEY in the INPUT USING optional unpend string, using one of the extended unpends acts just like an ordinary secondary unpend character.

If TURN_OFF(EXT_UNPEND) is executed, entering one of the extended unpend sequences will act as if the EXT_UNPEND had never been processed.

Once an extended unpend string has been defined, it does not need to be defined again, even when SWAPing or CHAINing to other Business BASIC programs. However, if a SWAP or CHAIN is performed to a non-Business BASIC program, the extended unpend table is assumed to be corrupted and must be redefined. The EXT_UNPEND flag is reset (see TURN_OFF(EXT_UNPEND)) and the unpend table is marked as being unusable. The program must execute EXT_UNPEND again to rebuild the extended unpend table.

Note: Once EXT_UNPEND has been defined, it cannot be redefined with a higher number of entries. If a program or set of programs issue EXT_UNPEND definitions with a varying number of entries, it is required that the first execution be for the maximum number of entries.

@Input also has extended input processing via the @DESC statement but there are several differences. EXT_UNPEND works across SWAPs and CHAINs. This means that once the extended unpend table is built, the string used to define it can be used in other statements. TURN_ON and TURN_OFF apply only to EXT_UNPEND sequences, not sequences defined using @DESC. The automatic build feature of EXT_UNPEND builds an extended unpend table with function key sequences 1 through 16; @DESC uses the four normal and seven special unpend characters.

Note: The extended unpend logic does not work when REPLYing to a task with a port number of 0 (background task). The sequence will be put into the string and the characters will be treated as any other characters. To REPLY to background tasks that use extended unpends, assign a pseudo port to the task.

Example

This section of code will use the default extended unpend table to decide which function key the user pressed. Executing EXT_UNPEND with a current length of 0 sets up the default table, and when the INPUT statement is executed, #UKEY will be set to the function key number if a function key is pressed.

900 DIM UNP$ (55) :unpend table - room for 16 3-byte sequences

  DIM X$ (1)

  EXT_UNPEND EC, UNP$, 3 :set UNP$ table to default for WYSE 60

950 PRINT "What do you want to do?"

  PRINT "F1 - Add a record"

  PRINT "F6 - Delete a record"

  PRINT "F10 - List 10 records from current position"

  PRINT "F16 - End the program"

  PRINT

  INPUT USING " ", "Press one of the above function keys", X$

  IF #UKEY <128 THEN GOTO 980

  #UKEY=#UKEY -128 :#UKEY=1-16

  IF #UKEY=1 THEN GOTO 1100 :Add a record

  IF #UKEY=6 THEN GOTO 1600 :Delete a record

  IF #UKEY=10 THEN GOTO 2000 :List records

  IF #UKEY=16 THEN

  PRINT "Program ending..."

  CLOSE

  END

  END IF

980 PRINT "You didn't press one of the keys - try again"

  GOTO 950

  .

  .


EXTRACT

Type

U/BL statement

Syntax

EXTRACT dest$, source$, delimiters, posn

Arguments

dest$ | A string variable to receive the field extracted.
source$ | A string expression containing the field to be extracted.
delimiters | A string expression containing the characters used to delimit fields within the source$ parameter.
posn | A numeric variable indicating the position of the delimiter immediately before the field to be extracted, and receiving the new delimiter position.

Description

The EXTRACT statement breaks a string up into substrings, based on the delimiter or delimiters specified. It extracts one substring each time it is used. Regardless of the contents of the delimiters parameter, a space is always regarded as a delimiter.

The source$ parameter is scanned for a delimiter character, starting from the character after the character specified by the posn parameter. The posn parameter should contain zero to start at the beginning of the string. If a delimiter is found, the substring between the delimiters is trimmed of blanks at both ends and placed in the dest$ parameter, and the location of the delimiter is placed in the position parameter. If a delimiter is not found (that is the end of the string is reached), the substring is extracted and -1 is placed in position.

Example

*list

00010 DIM LONG$[80],SHORT$[40],DELIM$[10]

00020 INPUT USING "","Source string...",LONG$

00030 IF LONG$="" THEN GOTO 00120

00040 INPUT USING "","Delimiters...",DELIM$

00045 IF DELIM$="" THEN GOTO 00040

00048 PRINT "The fields in the string are:"

00050 LET POSY=0

00070 EXTRACT SHORT$,LONG$,DELIM$,POSY

00080 PRINT POSY,SHORT$

00093 IF POSY<>-1 THEN GOTO 00070

00095 PRINT

00100 INPUT USING "","Source string...",LONG$

00110 GOTO 00030

00120 END

*run

Source string...IBM,COMPAQ,DELL,UNISYS,INTEL

Delimiters...,

The fields in the string are:

 4 IBM

 11 COMPAQ

 16 DELL

 23 UNISYS

-1 INTEL

Source string...18/02/1999

Delimiters.../

The fields in the string are:

 3 18

 6 02

-1 1999


@FORMAT

@FORMAT ---------- Convert and move @ fields from a record to a string

Type

U/BL statement.

Syntax

@FORMAT first field,number,record,string

Arguments

first field | A numeric expression specifying the first field to convert and move.
number | A numeric expression specifying the number of fields to move.
record | A string variable containing the field information to move.
string | A string variable into which the converted fields are moved.

Description

The @FORMAT statement converts and moves @ fields from a record to a string. It is similar to the @PRINT statement (performs the same conversion from binary to ASCII), but stores the converted field information in a string rather than outputting it to the terminal. The position in the target string where a field is moved is the 'x' co-ordinate of the particular field. This is set by the @SET or @SETFD statements.

Setting bit 3 of the flags byte skips the field and does not move the target string. When a field is skipped it still counts as one of the fields moved in the @FORMAT statement. To move fields 1,2,4,5, &7 set bit 3 for fields 3 and 6 but still specify the number of fields as 7.

If the DIMension of the target string is not at least as large as the highest numbered byte moved, a runtime error occurs. An error also occurs if the x-coordinate of a field to be moved is zero. The @FORMAT statement does not check or change the length of the target string. You should fill the target string with blanks before executing the @FORMAT statement.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


$F

$F ------------ Displays open files and shows their current GPOS values

Type

U/BL command.

Syntax

$F

Description

The $F command displays open files and shows their current GPOS values. U/BL allows more files to be OPENed than the operating system would normally allow, that is, U/BL maintains control over virtual channels. The $F command displays all files that are currently not physically OPENed indicated by a '*'. Also the resolution of links is shown.

See also

$FILES


$FILES

$FILES ------------ Displays open files and shows their current GPOS values

Type

U/BL command.

Syntax

$FILES

Description

The $FILES command displays open files and shows their current GPOS values. U/BL allows more files to be OPENed than the operating system would normally allow, that is, U/BL maintains control over virtual channels. The $FILES command displays all files that are currently not physically OPENed indicated by a '*'. Also the resolution of links is shown.

This command is an alias for the $F command.


$FLUSHPRT

$FLUSHPRT ---------- Flush out the BBSPOOL unique file

Type

U/BL statement or command.

Syntax

$FLUSHPRT er,channel

Arguments

er | A numeric variable which will be set to one of the following values: 0 - No error 27 - Illegal channel 44 - Channel not open
channel | The channel number that the printer was OPENed on

Description

The $FLUSHPRT statement flushes out the BBSPOOL unique file by executing the shell script/batchfile and re-positioning to the beginning of the spool file. As the contents of the file will be flushed, and therefore lost, it is necessary to make a copy of the spool file before control is passed back to the Basic program. Under UNIX this can be achieved by using the -c option on lp, for example.

This is useful when aligning pre-printed stationery, or when several reports are printed but the printer is only CLOSEd after the last report.

See also

BBSPOOL


$FORMAT

$FORMAT ---------- Copies formatted output into a string variable

Type

U/BL statement or command.

Syntax

$FORMAT result$ USING format$, expr [,expr]...

Arguments

result$ | A dimensioned string variable.
format$ | A string expression containing the format codes used to output expr to result$. For the description of the format codes, see section on the PRINT USING statement.
expr | Numeric or string expressions and numeric functions, but not string functions.

Description

The $FORMAT command stores formatted output in the result$ parameter, acting in a similar fashion to the PRINT USING statement. The difference is that the PRINT USING statement formats a 132 byte buffer and immediately prints it, whereas the $FORMAT command allows for other possibilities of manipulating the output.

This statement is similar but simpler to use than the 'L10' format within the PRINT USING statement.

Example

* list

00010 DIM I$[132],ITEM$[11]

00020 FOR K=1 TO 3

00030 READ ITEM$,AMT

00050 $FORMAT I$ USING "A11,2X,D12.2",ITEM$,AMT[K]

00060 PRINT I$

00070 NEXT K

00100 DATA "Income",15000000

00110 DATA "Expenditure",9000000

00120 DATA "Profit",6000000

* run

Income 150000.00

Expenditure 90000.00

Profit 60000.00

See also

PRINT USING


F_VAL

F_VAL ---------- Return the numeric value or a string as a $NUMERIC

Type

U/BL function

Syntax

F_VAL($string, decimals)

Arguments

string$ | A string expression containing the string to be converted.
decimals | A numeric variable which receives the number of digits to the right of the decimal point, or -1 if the conversion was not successful.

Description

The F_VAL function performs the same function as VAL, stripping leading and trailing spaces from a string and trying to convert it to a number. The difference is that the F_VAL function returns the result as a $NUMERIC quantity rather than as an integer.

The string can be successfully converted if it contains only the digits 0-9, with an optional decimal point and leading sign. If the string is successfully converted, it is returned as an integer, with the decimal places argument receiving the number of digits after the decimal point. If the string cannot be successfully converted, the decimals argument is set to -1 and the return value is the result of the conversion up to the point of failure.

If the result of the F_VAL function is stored in a $NUMERIC variable that supports fewer decimal places than in the result of the conversion, the result is rounded up to the available number of decimal places and no error results.

See also

$NUMERIC

VAL


FCB$

FCB$ ---------- Returns the File Control Block (FCB) information for the currently OPEN file

Type

U/BL statement

Syntax

b$=FCB$(chan)

Arguments

b$ | A string variable which receives the file's FCB information. This string must be DIMensioned to at least 80 bytes.
chan | A numeric expression specifying the channel number on which the file was OPENed.

Description

The FCB$ function returns the File Control Block (FCB) information for the file currently OPEN on channel chan, in the b$ parameter. The FCB$ function can only be used on the right hand side of a string assignment, it cannot be used anywhere else (such as in a string expression).

U/BL Rev 5.00 and above provide support for large files (files larger than 2GB). This feature is enabled if the platform supports the large file access system calls and if the BBLARGEFILES environment variable is set to Y. If Large File Support is enabled then the structure of the FCB block will be changed to handle larger record numbers and file sizes.

If Large File Support is enabled then:

  • The number of 512 byte sectors is stored in 6 bytes, the low order 3 bytes at position 19 – 21, and the high order 3 bytes at position 70 to 72.

  • The maximum number of records is stored in 4 bytes, the low order 3 bytes at position 22 to 24 and the high order byte at position 73.

  • The last record used is stored in 4 bytes, the low order 3 bytes at position 31 to 33 and the high order byte at position 74.

  • The first deleted record is stored in 4 bytes, the low order 3 bytes at position 34 to 36 and the high order byte at position 75.

  • The file length is stored in 8 bytes, the low order 4 bytes at position 38 to 41 and the high order 4 bytes at position 76 to 79.

  • The number of active records is stored in 3 bytes, the low order 3 bytes at position 48 to 50 and the high order byte at position 80.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Format of the buffer string returned

For all file types, unlisted bytes in the buffer string are null. All numeric quantities (marked with an '*') are stored in the string reverse order, that is, least significant byte first. To extract numeric values from the string, code similar to the following must be used:

REM Extract numeric info from FCB string and return it in NUMBER

REM Assumes info starts at byte in string that is pointed to by START

REM and the information is BYTES long. FCB info must be passed in F$.

REM Assumes TMP$ dimensioned to be at least BYTES long.

FOR PTR=START TO start+bytes-1

LET TMP$[TARGET,TARGET]=F$[PTR,PTR]

LET TARGET=TARGET-1

NEXT PTR

NUMBER=ASC(TMP$[1,BYTES])

Format of string for 'R' (SAVE files) and 'T' (text files) file types

Bytes | Contain
1-8 | CRAMmed version of the file's name
9-12 | Reserved
13-13 | File type - "R" or "T"
14-18 | Reserved
19-21 | Size of file in 512 byte blocks *
22-28 | Reserved
29-30 | Julian date of when the file was created *
31-37 | Reserved
38-41 | File length *
42-50 | Reserved
51-52 | Julian date of when the file was modified *
53-69 | Reserved
70-72 | Size of file in 512 bytes - high bytes * (if large files supported)
73-75 | Reserved
76-79 | File length - high bytes * (if large files supported)
80-80 | Reserved

Format of string for 'I' and 'J' type files (indexes)

Bytes | Contain
1-8 | CRAMmed version of the file's name
9-12 | Reserved
13-13 | File type - "I" or "J"
14-18 | Reserved
19-21 | Size of file in 512 byte blocks *
22-24 | Maximum number of index blocks *
25-26 | Reserved
27-28 | Key length (minus pointer, that is, length of date element) *
29-30 | Julian date of when the file was created *
31-33 | Number of the next available block in the index *
34-47 | Reserved
38-41 | File length *
42-50 | Reserved
51-52 | Julian date of when the file was last modified *.
53-69 | Reserved
70-72 | Size of file in sectors - high bytes * (if large files supported)
73-73 | Maximum number of index blocks - high byte * (if large files supported)
74-74 | Number of the next available block in the index - high byte * (if large files supported)
75-75 | Reserved
76-79 | File length - high bytes * (if large files supported)
80-80 | Reserved

Format of string for 'D' (linked-available) and 'U' (user-defined) type files

Bytes | Contain
1-8 | CRAMmed version of the file's name
9-12 | Reserved
13-13 | File type - "D" or "U"
16-18 | Reserved
19-21 | Size of file in 512 byte blocks *
22-24 | Maximum number of records the file can hold *
25-26 | Record length *
27-28 | Reserved
29-30 | Julian date of when the file was created *
31-33 | Number of the last record used in the file *
34-36 | Number of the first record on the deleted record chain *
37-37 | Reserved
38-41 | File length *
42-47 | Reserved
48-50 | Number of active records in the file *
51-52 | Julian date of when the file was last modified *.
53-69 | Reserved
70-72 | Size of file in sectors - high bytes * (if large files supported)
73-73 | Maximum number of records the file can hold – high byte * (if large files supported)
74-74 | Number of the last record used in the file – high byte * (if large files supported)
75-75 | Number of the first record on the deleted record chain – high byte * (if large files supported)
76-79 | File length - high bytes * (if large files supported)
80-80 | Number of active records in the file – high byte * (if large files supported)

Example

Example 1 - The following example demonstrates unpacking the FCB block if large files are supported:

PRINT "Display a File FCB<10>"

LET ks=10 \ maxrec=200

DIM fnam$[80]

INPUT "file:",fnam$

DIM f$[80],t$[20],fcbk$[80],name$[8],ugrp$[1]

DIM type$[1],rtflg$[1],x$[8]

OPEN FILE [0,5],fnam$

LET chan=0

GOSUB @unpack_fcb

GOSUB @display_fcb

CLOSE

END

@unpack_fcb

FCB (fcbk$,chan)

LET name$=UCM$(fcbk$[1,8])

LET x$=fcbk$[72,72],fcbk$[71,71],fcbk$[70,70]

LET x$(0)=fcbk$[21,21],fcbk$[20,20],fcbk$[19,19]

LET nsec=ASC(x$[1,6]) :size of file in 512 byte blocks/sectors

LET x$=fcbk$[73,73],fcbk$[24,24],fcbk$[23,23],fcbk$[22,22]

LET mrec=ASC(x$[1,4]) :maximum records

LET x$=fcbk$[26,26],fcbk$[25,25]

LET rlen=ASC(x$[1,2]) :record length

LET x$=fcbk$[30,30],fcbk$[29,29]

LET j=ASC(x$[1,2])

STMA 11,j,mm,dd,yy

LET cdat=dd*10000+mm*100+yy :date created

LET x$=fcbk$[74,74],fcbk$[33,33],fcbk$[32,32],fcbk$[31,31]

LET lrecu=ASC(x$[1,4]) :last record used

LET x$=fcbk$[75,75],fcbk$[36,36],fcbk$[35,35],fcbk$[34,34]

LET fdel=ASC(x$[1,4]) :first record on deleted record chain

LET x$=fcbk$[80,80],fcbk$[50,50],fcbk$[49,49],fcbk$[48,48]

LET noact=ASC(x$[1,4]) :Number of active records

LET x$=fcbk$[52,52],fcbk$[51,51]

LET j=ASC(x$[1,2])

STMA 11,j,mm,dd,yy

LET lwdat=dd*10000+mm*100+yy :Date last modified

IF type$="i" THEN

LET x$=fcbk$[28,28],fcbk$[27,27]

LET klen=ASC(x$[1,2]) :key length

END IF

LET x$=fcbk$[79,79],fcbk$[78,78],fcbk$[77,77],fcbk$[76,76]

LET x$(0)=fcbk$[41,41],fcbk$[40,40],fcbk$[39,39],fcbk$[38,38]

LET nbot=ASC(x$) :file size in bytes

IF type$="d" THEN

LET x$=fcbk$[69,69],fcbk$[68,68],fcbk$[67,67]

LET lrecr=ASC(x$[1,3]) :last record number

END IF

RETURN

@display_fcb

PRINT "name: ";name$

PRINT "file type: ";type$

PRINT "bit flags: ";bflgs

PRINT "number of sectors: ";nsec

IF type$="d" THEN

PRINT "maximum no of records in file: ";mrec

PRINT "record length: ";rlen

END IF

IF type$="i" THEN

PRINT "maximum no of sectors in file: ";mrec

PRINT "block length: ";rlen

PRINT "key length: ";klen

END IF

PRINT using "'date of creation: ','  /  /',t0,d8.0",cdat

PRINT "last record no used: ";lrecu

PRINT "first deleted record no: ";fdel

IF type$="d" THEN

PRINT "last record number read: ";lrecr

END IF

PRINT "number of bytes: ",nbot

PRINT

RETURN

Example 2

:

02000 REM Unpack and Display a File's FCB

02010 FBK$=FCB$(CHAN)

02020 LET NAME$=UCM$(FBK$[1,8])

02030 TYPE$=FBK$[13,13]

00240 IF TYPE$<>"R" AND TYPE$<>"U" THEN

02050 LET X$=FBK$[21,21],FBK$[20,20],FBK$[19,19]

02060 LET NSEC=ASC(X$[1,3])

02070 LET X$=FBK$[24,24],FBK$[23,23],FBK$[22,22]

02080 LET MREC=ASC(X$[1,3])

02090 LET X$=FBK$[26,26],FBK$[25,25]

02100 LET RLEN=ASC(X$[1,2])

02110 ENDIF

02120 LET X$=FBK$[30,30],FBK$[29,29] \ J=ASC(X$[1,2])

02130 STMA 11,J,MM,DD,YY

02140 IF TYPE$<>"R" AND TYPE$<>"T" THEN

02150 LET CDAT=DD*10000+MM*100+YY

02160 LET X$=FBK$[33,33],FBK$[32,32],FBK$[31,31]

02170 LET LRECU=ASC(X$[1,3])

02180 IF TYPE$<>"D" AND TYPE$<>"U" THEN

02190 LET X$=FBK$[36,36],FBK$[35,35],FBK$[34,34]

02200 LET FDEL=ASC(X$[1,3])

02210 ENDIF

02220 ENDIF

02230 LET X$=FBK$[50,50],FBK$[49,49],FBK$[48,48]

02240 LET NOACT=ASC(X$[1,3])

02250 LET X$=FBK$[52,52],FBK$[51,51] \ J=ASC(X$[1,2])

02260 STMA 11,J,MM,DD,YY

02270 LET LWDAT=DD*10000+MM*100+YY

02280 PRINT "File Name: ";NAME$

02290 PRINT "File Type: ";TYPE$

02300 PRINT "Number of Sectors: ";NSEC

02310 IF TYPE$="D" OR TYPE$="U" THEN

02320 PRINT "Maximum No of Records in File: ";MREC

02330 PRINT "Record Length: ";RLEN

02340 ELSE

02350 IF TYPE$="I" OR TYPE$="J" THEN

02360 PRINT "Maximum No of Sectors in File: ";MREC

02370 LET X$=FBK$[28,28],FBK$[27,27] \ KLEN=ASC(X$[1,2])

02380 PRINT "Key Length: ";KLEN

02390 ENDIF

02400 END IF

02410 PRINT USING "'Date of Creation: ',' / /',T0,D8.0",CDAT

02420 IF TYPE$="D" OR TYPE$="U" THEN

02430 PRINT "Last Record Number Used: ";LRECU

02440 PRINT "First Deleted Record No: ";FDEL

02450 PRINT "No of Active Records: ";NOACT

02460 ELSE

02470 IF TYPE$="I" OR TYPE$="J" THEN

02480 PRINT "Next Available Block: ";LRECU

02490 ENDIF

02500 ENDIF

02510 PRINT USING "'Date Last Written to: ',' / /',T0,D8.0",LWDAT

02999 RETURN

:

See Also

CHECK


FETCH

FETCH ---------- Returns results from a previously-executed SQL query

Type

SQL Access Command

Syntax

FETCH(CUR$, OBUF$, STAT)

Arguments

CUR$

The name of a previously-executed SQL Access cursor

OBUF$

A buffer to receive the data for the next row of output from the SQL query.

STAT

A numeric variable to receive the status return. STAT returns one of the following codes:

-1 | Indicates a datasource specific error; if this occurs, the program should use the SQLERR statement to determine what that error is.
0 | No error
1 | Cannot find cursor
2 | Output buffer is too small
3 | Success with further information. Use the SQLERR statement to determine the further details.
other | Driver-specific error code

Description

The FETCH statement returns the next row of output data from the previously executed SQL query, associated with the specified SQL Access cursor. The data returned is packaged in the output buffer (the OBUF$ parameter) according to the format previously defined by the SQL statement when the SQL Access cursor was declared.

Example

The following source code retrieves a set of rows from the cursor "GETPROD", which has previously been prepared and successfully executed.

00100 FETCH ("GETPROD",OBUF$,STAT)

00110 IF STAT<>0 THEN

00120 GOSUB @Process_SQL_Error

00130 END IF

00200 DO WHILE STAT=0

00210 UNPACK "A30LC", OBUF$, PNAME$, PRICE, QTYOH

00220 PRINT "Product Name: ",PNAME$

00230 PRINT "Price:",PRICE

00240 PRINT "Quantity: ",QTYOH

00250 PRINT

00260 INPUT "Press Any Key To Continue",X$

00270 FETCH ("GETDATA",OBUF$,STAT)

00280 IF STAT<>0 & STAT<>-1 THEN

00290 GOSUB @Process_SQL_Error

00300 LET STAT=0 : Force exit from loop

00310 ENDIF

0032 0 END LOOP

See Also

EXEC

SQL

SQLERR


FILEBROWSE

FILEBROWSE ---------- Browse for a file on the client PC

Type

Windows Object Command

Syntax

FILEBROWSE(FILEPATH$, EXTENSION$, MODE [, STAT])

Arguments

FILEPATH$ | Specifies the initial filename displayed, and receives the selected filename.
EXTENSION$ | Specifies the default file extension to be browsed for, without the period '.'
MODE | Specifies the initial open mode, and receives whether OK or CANCEL was returned.
STAT | Optional status return.

Description

This statement displays a Windows file browser to enable the user to select a file. Initially the browser displays files of type EXTENSION$, displaying FILEPATH$ as the default file. The MODE parameter is used to specify the type of dialog displayed. It is set to:

  • 1 for an Open File dialogue

  • 0 for a Save File dialogue

The file selected when the dialog exits is returned in FILEPATH$ with the MODE parameter receiving which button was pressed:

  • 1 for OK

  • 2 for Cancel

If an error occurs, the MODE parameter receives a 0 and the error code is returned in the STAT variable.

Example

@OpenTXT

REM Subroutine to process a temporary text file

REM Assumes TMPTXT$ dimensioned to receive file name

LET TMPTXT$="c:\temp" : * Start in c:\temp *

LET OPENDIALOG=1 : * Mode 1 is Open mode *

FILEBROWSE(TMPTXT$,"TXT",OPENDIALOG)

IF OPENDIALOG=0 THEN

GOSUB @Error

ELSE

IF OPENDIALOG=1 THEN

GOSUB @ProcessFile

ELSE

REM Operation cancelled

END IF

END IF

RETURN


FILELOCK

FILELOCK ---------- Locks or unlocks I/O activity to a file

Type

U/BL statement

Syntax

FILELOCK FILE(channel) ON

FILELOCK FILE(channel) OFF

Arguments

channel

A numeric expression specifying the channel number on which a file is opened.

Description

The FILELOCK statement sets or resets a flag in the open file table of the specified file. When the flag is set, any attempted I/O (for example, reads, writes), with the exception of file OPEN, CLOSE, or a file FLUSH by other tasks, results in a BASIC error #-157 being returned. A read by another task, even with the READLOCK on, is not permitted when a file is FILELOCKed. The flag is set by specifying the ON format.

If you attempt to lock a file is when there are records that are locked, U/BL waits up to 3 seconds for the record locks to be removed. If the 3 seconds elapse before all the record locks for the file are cleared, a #ERR=30 is returned. When a FILELOCK is attempted but is waiting for record locks to clear, all I/O is permitted to the file except more record locks.

Note: If you this command and permit all file I/O while a task is waiting for the locks on the file to be removed, a read operation could begin and, before it is finished, another task could lock the file and write to the same record that was being read. Before doing a read, the record should be SLOCKed to prevent this situation from occurring.

The lock flag is reset using the OFF format. If the task attempting to turn the lock flag OFF is not the task that has it locked a BASIC error #-157 is returned.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

100 OPEN FILE (0, 5) , "TEST1" :Channel 0, mode 5

200 FILELOCK FILE (0) ON :Lock file

300 DELAY 30*10 :Leave locked 30 seconds

400 FILELOCK FILE (0) OFF :Unlock file

500 CLOSE

600 END


FILETRANSFER

FILETRANSFER ---------- Allow file transfer between the U/Gi client and a U/BL server

Type

Windows Object Command

Syntax

FILETRANSFER(SERVFILE$, CLIFILE$, MODE [, STAT])

Arguments

SERVFILE$ | The path to the file on the server machine (the one running U/BL), regardless of the direction of the file transfer.
CLIFILE$ | The path to the file on the client machine (the one running U/Gi).
MODE | Specifies how the file transfer will operate, including transfer direction, type of transfer and update options.
STAT | Optional error code.

Description

The FILETRANSFER statement allows the bi-directional transfer of files between the server machine running U/BL and the client PC running U/Gi. The source file and target for the file transfer are defined in the two string parameters, SERVFILE$ and CLIFILE$. The following predefined directory macros can be used in the CLIFILE$ parameter to specify predefined directories on the client PC:

  • $(WINDIR) The Windows directory on the client·

  • $(WINSYSDIR) The Windows System directory:

system subdirectory of the Windows directory on Windows 95 or Windows 98

system32 subdirectory of the Windows directory under Windows NT or Windows 2000

  • $(TMPDIR) The temporary directory

  • $(TEMPDIR) Alias for the temporary directory

For example:

010 REM * FTMANGLE *
020 REM * TESTS FILETRANSFER DIR MANGLING FUNCTIONS *
100 DIM A$[100]
110 OPEN FILE[0,0],"FTM.TST"
120 PRINT FILE[0],"Hello"
130 CLOSE
140 FILETRANSFER "FTM.TST","$(WINDIR)\FTM1.TST",0,STAT
150 FILETRANSFER "FTM.TST","$(WINSYSDIR)\FTM2.TST",0,STAT
160 FILETRANSFER "FTM.TST","$(TMPDIR)\FTM3.TST",1,STAT

Dependant on the MODE parameter, the transfer mechanism can automatically convert between UNIX format text files where the line terminator is a single carriage return, "<13>", and the MD/DOS or Windows format where the line terminator is a carriage return followed by a line feed, "<13><10>".

An additional feature of FILETRANSFER is that it can intelligently decide whether or not a file needs to be transferred. Options exist to prevent the operation if the target file already exists or if the source file is not newer than the target. These functions are also controlled by the MODE parameter which is a bitmask. Multiple flags can be selected by ORing the flags together, for example, to perform a textual file transfer from the client to the server, set MODE to '2 U 1' or '3'. The functions available and controlled by the MODE parameter are:

Value

Description

1

Transfer the file from the client to the server (U/Gi to U/BL), rather than in the default direction of server to client (from U/BL to U/Gi).

2

Transfer in text mode (perform CR/LF to CR translations if the target file is on UNIX; CR to CR/LF translation if the source file is on UNIX).

4

Perform the transfer only if the target file does not already exist

8

Perform the transfer only if the source file is newer than the target

64

Self registration of ActiveX controls. Indicates that the file being transferred is an ActiveX control and that U/Gi should attempt to register the file on the client system.

When used in conjunction with mode 8 (REFRESH), this can ensure that the latest copy of an ActiveX control is installed on the client PC without user intervention.

A STAT of 22 is returned if the registration fails or if self registration is attempted on a file which is not a self registering ActiveX control.

Note: Some older ActiveX controls are not capable of self-registration.

128

The transferred file will be appended onto the destination file.

Note: FILETRANSFER is designed to work with assured connections. It does not provide any error correction facilities. Any transmission corruptions will be reflected in the transferred file. When using TCP/IP, the networking protocol should ensure that no corruption occurs. When using a serial connection via a modem try to use the modem's error correction facilities. However, should corruption occur between either modem and its local computer (for instance data overrun) then the FILETRANSFER will result in a corrupt file.

Example

The program demonstrates transferring a file in text mode from the server to the client, transferring the file back from the client to the server, and then transferring both ways again but appending to the files previously transferred.

The program (written for UNIX U/BL) requires the file atappend.txt to exist, before it can be successfully run:

DIM RET$[200]

DIM SERVFILE$[50]

DIM CLIFILE$[50]

LET SERVFILE$="atappend.txt"

LET CLIFILE$="btappend.txt"

LET TEXTFLAG=2

LET MODE=0+TEXTFLAG

FILETRANSFER(SERVFILE$,CLIFILE$,MODE,STAT)

PRINT "StoC: atappend.txt -> btappend.txt"

PRINT "stat=";STAT

IF STAT THEN STOP

LET MODE=1+TEXTFLAG

LET SERVFILE$="ctappend.txt"

LET CLIFILE$="btappend.txt"

FILETRANSFER(SERVFILE$,CLIFILE$,MODE,STAT)

PRINT "CtoS: btappend.txt -> ctappend.txt"

PRINT "stat=";STAT

IF STAT THEN STOP

REM $EXECUTE "cmp atappend.txt ctappend.txt",RET$,ER

IF ER THEN

PRINT "FAILED !cmp atappend.txt ctappend.txt"

STOP

END IF

REM append it on top

LET MODE=1+TEXTFLAG+128

FILETRANSFER(SERVFILE$,CLIFILE$,MODE,STAT)

PRINT "CtoS append: btappend.txt >> ctappend.txt"

PRINT "stat=";STAT

IF STAT THEN STOP

REM append atappend.txt to btappend.txt

LET SERVFILE$="atappend.txt"

LET CLIFILE$="btappend.txt"

LET MODE=0+TEXTFLAG+128

FILETRANSFER(SERVFILE$,CLIFILE$,MODE,STAT)

PRINT "StoC append: atappend.txt >> btappend.txt"

PRINT "stat=";STAT

IF STAT THEN STOP

REM copy result back to check

LET MODE=1+TEXTFLAG

LET SERVFILE$="dtappend.txt"

LET CLIFILE$="btappend.txt"

FILETRANSFER(SERVFILE$,CLIFILE$,MODE,STAT)

PRINT "CtoS : btappend.txt -> dtappend.txt"

PRINT "stat=";STAT

REM $EXECUTE "cmp dtappend.txt ctappend.txt",RET$,ER

IF ER THEN

PRINT "FAILED ! cmp dtappend.txt ctappend.txt"

STOP

END IF

PRINT "Test Passed!"

See Also

Error codes

UBLNTHEX


FILL$

FILL$ ---------- Fills a string or substring with a given ASCII value

Type

U/BL function

Syntax

string$ = FILL$(value [,length])

Argument

string$ | A string variable which is filled with the value.
value | ASCII value of the character to pad with.
length | Number of bytes to pad. The default is the whole string.

Description

The FILL$ function pads a string with the specified character, usually null or space. Unless a length is specified, the entire string or substring will be padded with this character. If a length is specified, only that number of bytes will be padded or the full string/substring if it is shorter than the length specified.

Example

* dim x$[5]

* x$=fill$(32,3),fill$(0)

* $H x$

000001 20 20 20 00 00

* x$(3,4)=fill$(255)

* $H x$

000001 20 20 ff ff 00


FOR

FOR ---------- Allows a loop to be performed a given number of times

Type

U/BL statement

Syntax

FOR counter = start TO end [STEP increment]

   statements

NEXT counter

Arguments

counter | A numeric variable used as the loop counter.
start | A numeric expression which sets the initial value of the counter.
end | A numeric expression against which the counter value is tested. The loop ends once the counter value is greater than the value of end (or less than the value of end if the increment is negative).
increment | A numeric expression representing the amount by which the counter is altered by each time the loop is executed. A negative value for the increment causes the control variable to be decremented by the specified amount on each iteration of the loop. If not specified, the increment defaults to 1.

Description

The FOR statement allows a statement or several statement s to be performed a specified number of times. The value of counter is set to the value of start, and then it is tested against end. If counter is less than or equal to end, and increment is positive or not specified, then the statements between the FOR and the NEXT are performed. The increment is then added to the counter and the test is repeated. If the increment is negative, a similar procedure is followed, but counter must be greater than or equal to end for the loop to continue.

If end is less than start when the FOR statement is first reached (and the increment is positive) the statements between the FOR and the NEXT are not executed at all, or vice versa if the increment is negative.

It is possible to jump out of FOR loops safely, but never safe to jump into one. Jumping out of loops is not usually considered good programming practise, however, if done the user may wish to use the STMA 8,1 statement to reset the FOR NEXT stack. The counter may be modified in a loop but this is not considered as good programming practice.

FOR loops may be nested but they must not overlap. For compatibility with B32 Business Basic, U/BL supports up to 20 levels of nested FOR/NEXT loops.

Example

1. An example of a single for loop:

*list

00010 FOR I=1 TO 10

00020 PRINT I;

00030 NEXT I

00040 PRINT

00050 PRINT "I ends with the value ";i

* run

1 2 3 4 5 6 7 8 9 10

I ends with the value 10

2. An example of a nested for loop:

*list

00010 FOR I=1 TO 4

00020 FOR J=1 TO 4

00030 PRINT I*J;

00040 NEXT J

00050 PRINT

00060 NEXT I

* run

1   2   3   4

2   4   6   8

3   6   9   12

4   8   12   16

3. An example of a single loop with a negative step:

*list

00010 FOR I=5 TO -5 STEP -3

00020 PRINT I;

00030 NEXT I

*run

5 2 -1 -4


FORCE

FORCE ---------- Forces execution of a program in another task

Type

U/BL statement.

Syntax

FORCE task,program$

Arguments

task | A numeric expression that is the task number under which the program is to be executed
program$ | A string variable or literal containing the name of the program to be executed with optional command line arguments

Description

This statement forces execution of a program in another task space. Note that the task number specified:

  • Must be valid for the current system configuration

  • Cannot be equal to your task (SYS (9))

  • Must not be active (not have a program executing).

You can optionally pass command line arguments in the string expression by adding them to the end of the string. The new task uses the same account, same security level, and the same searchlist as the current task. When execution is complete, the task is logged off.

The new task does not need to have a port number associated with it. However, if no port is associated with the task and the program performs terminal output, the output is discarded. Terminal input causes the task to wait until a port is assigned, at which time execution is resumed.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Possible errors

A BASIC error #-78 occurs if the task specified in the FORCE is invalid (that us, it is not in the current system configuration).

A BASIC error #-78 occurs if you specify your own task in the FORCE.

A BASIC error #-78 occurs if an active task is specified in the FORCE.

Example

This example demonstrates the use of the FORCE statement. It prompts the operator for a text filename and task number. It then forces the TYPE program in the specified task to type the file contents to $LPT.

Note: The variable NTASKS varies from system to system.

10 DIM X$ (80) ,FILES$ (18) \#ERR=0 \ NTASKS=10

15 PRINT \ INPUT USING " ", "Filename: " ,@(-10, 20) ,FILE$

20 #ERRJMP OFF \ CHECK FILE$ ,X$ \ #ERRJMP ON

25 IF #ERR <>0 THEN PRINT "Invalid filename" \ GOTO 10

30 IF X$ (13, 13) <> "T" THEN PRINT "Invalid filename" \ GOTO 10

35 PRINT \ INPUT USING " " ,"Task number : " ,@(-10, 2) ,X$

40 TASK=VAL (X$, E)

45 IF (TASK<1 ? TASK=SYS (9) ? TASK>NTASKS ? E <>0) THEN

50 PRINT "Invalid task" \ GOTO 35

55 END IF

60 X$="TYPE / P=1 ",FILE$

65 #ERRJMP OFF

  FORCE TASK, X$ : FORCE "TYPE / P=1" ON TASK

  #ERRJMP ON

70 IF #ERR=0 THEN PRINT "Task forced" ELSE PRINT "Unable to force task"

80 END


FORCERR

FORCERR ---------- Invokes the ON ERR logic

Type

U/BL statement.

Syntax

FORCERR error number

Arguments

error number

A numeric expression that specifies the error number.

Description

The FORCERR statement invokes the ON ERR logic with a specified error number. When executed, BASIC acts exactly as if a run-time error occurred. The FORCERR statement has been provided to support both generalized and customized error handling routines.

The FORCERR statement is equivalent to the STMA 19 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Examples

1. This demonstrates the use of FORCERR

20 ON ERR THEN GOTO 800

30 INPUT USING " " ,"ENTER A NUMBER FROM 1 TO 50 ",X

40 IF X<1 ? X>50 THEN FORCERR 1040

50 PRINT "YOU FOLLOW DIRECTIONS VERY WELL"

60 GOTO 900

800 : ERROR HANDLING ROUTINE

810 IF SYS (7)=1040 THEN

  PRINT "You didn't do what I told you"

  GOTO 900

  END IF :

: WHEN HERE, WE GOT A TRUE ERROR - NOT THE ONE FROM FORCERR

:

  PRINT

  PRINT " ERROR" ;SYS (7) ;"AT" ; SYS (20)

900 END

2. The following lines can be added to a program to reset the value of SYS (7) to 0.

ON ERR THEN GOTO 9980

  FORCERR 0 :Invoke Error 0

9980 ON ERR THEN GOTO 9900 :Standard Error Handler


FROMJULIAN

FROMJULIAN ---------- Converts a Julian date to a month, day, and year

Type

U/BL statement.

Syntax

FROMJULIAN Jdate,month,day,year

Arguments

Jdate | A numeric expression which evaluates the Julian date to be converted, representing the number of days since Jan 0, 1968
month | A numeric variable into which is stored the month of the converted date.
day | A numeric variable into which the day of the converted date is stored.
year | A numeric variable into which the year of the converted date is stored.

Description

The FROMJULIAN statement converts a Julian date into its equivalent month, day, year representation.

A Julian date is one which is expressed as a number of days from a given point. In the case of Business BASIC the given point against which all Julian dates are referenced is the start of 1968. The first of January 1968 is Julian date 1, the second of January 1968 is Julian date 2 and so forth.

The Julian date processing algorithms in U/BL are highly controlled by the BBJULIANFLAGS environment variable (and to a lesser extent BBDATEWINDOW). Dependant on the setting of this environment variable, the operation of any Julian date processing will alter in line with the settings of these environment variables.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This demonstrates the use of FROMJULIAN:

10 INPUT USING " " ,"ENTER A JULIAN DATE (1-65535) ",JDATE

15 IF JDATE=0 THEN GOTO 10

20 FROMJULIAN JDATE, MO, DA,YR :CONVERT DATE

30 CDATE=MO*10000+DA*100+MOD(YR,100)

40 PRINT USING " 'THIS DATE=' , ' / /' ,T0,D8.0" ,CDATE

50 END

See also

BBDATEWINDOW

BBEXTENSION

BBJULIANFLAGS

BBSDOSDATE

$DATE$

STMA 12

STMA 11

SYS(152)

TOJULIAN

$VDATE


@GET

@GET ------------ Retrieve a field definition

Type

U/BL statement.

Syntax

@GET field number,string

Arguments

field number | A numeric expression which specifies the field number of the field previously defined in a @SET statement.
string | A string variable used to store the field definition of the specified field. It must be DIMensioned to at least 9 bytes.

Description

The @GET statement retrieves the definition of a field that has been previously defined by the @SET or @SETSD statements. The field definition is stored in the specified string. The string must be dimensioned to at least 9 bytes or a run-time error occurs.

After moving the information to the string the current length of the string is set to 9. The 9 bytes are described in the @SET statement.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

See the example for @DISPSUB.


@GETFIELD

@GETFLD ---------- Extract a key from a record string

Type

U/BL statement.

Syntax

@GETFLD first field,number,record,key field

Arguments

first field | A numeric expression which specifies the first field to extract.
number | A numeric expression which specifies the number of fields to extract.
record | A string variable which contains the fields to be extracted and moved.
key field | A string variable which is moved to the extracted fields. This string contains the extracted fields in consecutive locations.

Description

The @GETFLD statement extracts the specified number of fields from the record string and moves them to the key field starting with the specified first field number. The statement is primarily used to extract and index field from a record when the key is comprised of multiple fields in non-sequential byte location. However it can also be used to extract any @SET fields from the record.

The field specs defined by the @SET statements determine the location of the fields. When the first field has been extracted it is stored starting at the first byte of the key field string. The rest of the fields are appended, resulting in the key field string being a concatenation of all the specified fields.

The run-rime error #ERR=84 occurs if the length of the record string is not at least as large as the highest numbered byte extracted. For example, if a field is defined as 8 bytes starting at byte 63, then the current length of the record string must be at least 90. The run-rime error #ERR=83 occurs if the dimension of the key field is not at least as large as the number of bytes moved. When a field is moved there is no conversion performed as with the @FORMAT statement.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

See the examples in @PRINT and @INPUT.


$G

$G ------------ Displays program information

Type

U/BL command.

Syntax

$G

Description

The $G command displays the following program information:

  • the current program

  • the previous program

  • last line executed

  • the line number and destination of the last GOTO statement

  • the line number and destination of the previous GOTO statement

  • the last U/BL error number

  • the last operating system error number

  • the channel of the last I/O

  • the line number of the active ON ERR trap

  • the line number of the active ON IKEY trap

  • the last line number to be encountered before the last error

  • the last line label to be encountered before the last error

  • the physical line number of the last error

  • the line number of the last IKEY (physical line number also shown)

  • the GOSUB/RETURN stack.

The $G command is analogous to Data General Business BASIC's "PD" utility and is based on the B32 Business Basic $STATUS command.

See also

STMA 9

SYS (200)


$GET_VALUE

$GET_VALUE ---------- Retrieves the value of various system parameters

Type

U/BL statement or command.

Syntax

$GET_VALUE(parameter,var)

Arguments

parameter | A system parameter.
var | A numeric variable which will receive the parameter's value.

Description

The $GET_VALUE command retrieves the value of various system parameters which are set either by the $SET_VALUE command, or by default are one of the following: NL1, NL2, SCREEN_REFRESH, CONSOLE, LINE_LEN, U_SCD, U_USR1, U_USR2, DATE_IN, DATE_OUT, DATE EDIT, ACCOUNT.

See also

$SET_VALUE


$GETENV

$GETENV ---------- Retrieves the value of a given environment variable

Type

U/BL statement or command.

Syntax

$GETENV env$,val$

Arguments

env$ | A string expression specifying the environment variable to be retrieved.
val$ | A string variable to receive the value of the environment variable retrieved.

Description

The $GETENV command retrieves the value of a given environment variable.

Example

01000 REM $GETENV "BBROOT",R$

01010 PRINT R$

See also

$PUTENV


_GET27BUF

GET27BUF ---------- Stores the contents of the STME 27 buffer for future use

Type

U/BL command and statement

Syntax

GET27BUF(str$)

Arguments

str$

A string variable which will receive the current contents of the input buffer. The maximum length of str$ is the same as the input buffer - 256 bytes.

Description

The GET27BUF statement allows users to store the contents of the STME 27 buffer for future use. This is especially useful where there is a need to preserve an original INPUT string over a hot-key to a program or subroutine which itself performs an INPUT (thus destroying the contents of the STME 27 buffer).

Example

DIM I$[80],S$[256]

STME 27,ER,"Original INPUT",15

HOT 1,1000

PRINT @(-30);@(3,1);"Press the first hotkey now: ";

INPUT "",I$

IF I$<>"Original INPUT" THEN STOP

END

01000 GET27BUF (S$)

STME 27,ER,"New INPUT",10

PRINT

INPUT @(5,1),"Now Press <RETURN> : ";

PRINT @(3,1),"Now Press <RETURN> :<7> ";

STME 27,ER,S$,LEN(S$)+1

RETURN

* run

Press the first hotkey now: Original INPUT<hotkey 1 pressed here>

Now Press <RETURN> : New INPUT<RETURN key pressed here>

Screen now reads:

Now Press <RETURN> : Original INPUT<cursor here>

Now Press <RETURN> : New INPUT

See also

STME 27


GETACCT

GETACCT ---------- Retrieves the six-byte SuperDOS account number

Type

U/BL statement

Syntax

GETACCT dest var[,task]

Arguments

dest var | A string variable into which the account number is returned
task | An optional numeric expression containing a task number. If you omit this argument, the statement uses the current task.

Description

The GETACCT statement moves the six-byte account number into the destination string. This account number is determined by the password that has been used to sign on. The Password File contains a record for every valid password. Each record has an account number. If the task specified is not signed on, the destination string is set to null.

If the DGCOMP switch is ON, the sixth byte of the account name returned in the destination string will contain the terminal type (see STMA 1,0,n) as a 1-byte ASCII character. This is only supported for the current task. If the optional expression for another task is present, DGCOMP will have no effect.

The GETACCT statement is equivalent to the STMA 9,0 statement.

Possible errors:

The Basic error #-78 occurs if a task number is specified but is not a valid task number, that is, the task number is less than 1 or greater than the highest valid task number.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See STMA 9


GETCMD

GETCMD ---------- Retrieves the command line passed to a program

Type

U/BL statement.

Syntax

GETCMD cmdline$

Arguments

cmdline$

A string variable to receive the command line.

Description

The GETCMD statement retrieves any command line arguments passed to a program by the Command Line Processor (CLP) or another program. The information passed includes any characters that follow the program name in the command line. When a program begins execution, the command line arguments are stored in the task's Input/Output buffer space. The command line must thus be retrieved (using a GETCMD statement) prior to executing any I/O operations, as these operations overwrite the existing information in the I/O buffer. The current length of the string variable is changed only if the number of characters moved is greater than the previous length.

A total of 78 characters can be passed. However, setting the BBLONGCMD environment variable to Y allows a 200 char argument list to be passed in the GETCMD buffer via the command line or the SWAP and CHAIN commands. 100 chars are also allowed for the file or path name, giving an effective total command line length of 300 chars.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This example demonstrates the use of the GETCMD statement. The command line used to run a program called FIXPORT contains an argument ("/PORT=n") indicating a port number to be fixed.

PORT=0

DIM CMDLIN$ (78) ,X$ (10)

GETCMD CMDLIN$

X=POS (CMDLIN$, "/PORT=" , 1)

IF X THEN : User specified port

Y=LEN (CMDLIN$)

PORT=VAL (CMDLIN$ (X+6, Y) ,E)

END IF

IF PORT=0 THEN

INPUT USING " ", "Enter Port to Fix :" ,X$

PORT=VAL (X$, E)

IF E THEN GOTO 20

END IF

  .

  .


GETCOLOR

GETCOLOR ------------ Retrieves the color of a Windows Object

Type

Windows Object Command.

Syntax

GETCOLOR(ID, FG, COLOR [,STAT])

Arguments

ID | The ID number of the Windows Object.
FG | The value of FG can either be 0 or 1, where: 0 - means "get the background color" 1- means "get the foreground color".
COLOR | This is a variable which indicates the color. (See below for more information.)
STAT | The status variable.

Description

The GETCOLOR statement gets the color of a Windows Object.

The meaning of COLOR variable is bit-significant. The GETCOLOR statement always returns an RGB value. The format of an RGB value is as follows:

For example:

bright red | 255 | (0 * 65536) + (0 * 256) + (255 * 1)
dark red | 128 | (0 * 65536) + (0 * 256) + (128 * 1)
bright yellow | 65535 | (0 * 65536) + (255 * 256) + (255 * 1)
orangy yellow | 32896 | (0 * 65536) + (128 * 256) + (128 * 1)
bright purple | 16711935 | (255 * 65536) + (0 * 256) + (255 * 1)


GETCOM1

GETCOM1 ---------- Retrieves inter-program communication code 1

Type

U/BL statement.

Syntax

GETCOM1 dest var

Arguments

dest var

A numeric variable into which the value of the code is returned

Description

The GETCOM1 statement moves the value of communication code 1 into the dest var parameter. Communication code 1 is a two byte inter-program communication code usually used as flags when executing a SWAP or CHAIN between programs.

The GETCOM1 statement is equivalent to the STMA 1,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program performs a SWAP to the program below which sets a code.

10 SWAP "B" :RUN PROG B TO SET CODE

20 GETCOM1 X :GET INTER-PROGRAM CODE 1

30 PRINT X :PRINT THE CODE

40 END

Program "B" gets the inter-program code value from the user and sets it.

10 INPUT USING " " ,"ENTER CODE 1 ",X

20 SETCOM1 X :SET THE CODE

30 END


GETCOM2

GETCOM2 ---------- Retrieves inter-program communication code 2

Type

U/BL Statement.

Syntax

GETCOM2 dest var

Arguments

dest var

A numeric variable into which the value of the code is returned

Description

The GETCOM2 statement moves the value of communication code 2 into the dest var parameter. Communication code 2 is a two byte inter-program communication code usually used as flags when executing a SWAP or CHAIN between programs.

The GETCOM2 statement is equivalent to the STMA 1,2 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program performs a SWAP to the program below which sets a code.

10 SWAP "B" :RUN PROG B TO SET CODE

20 GETCOM2 X :GET INTER-PROGRAM CODE 2

30 PRINT X :PRINT THE CODE

40 END

Program "B" gets the inter-program code value from the user and sets it.

10 INPUT USING " " ,"ENTER CODE 2 ",X

20 SETCOM2 X :SET THE CODE

30 END


GETCOM3

GETCOM3 --------- Retrieves inter-program communication code 3

Type

U/BL Statement.

Syntax

GETCOM3 dest var

Arguments

dest var

A numeric variable into which the value of the code is returned

Description

The GETCOM3 statement moves the value of communication code 3 into the dest var parameter. Communication code 3 is a two byte inter-program communication code, usually used as flags when executing a SWAP or CHAIN between programs.

The GETCOM3 statement is equivalent to the STMA 1,3 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program performs a SWAP to the program below which sets a code.

10 SWAP "B" :RUN PROG B TO SET CODE

20 GETCOM3 X :GET INTER-PROGRAM CODE 3

30 PRINT X :PRINT THE CODE

40 END

Program "B" gets the inter-program code value from the user and sets it.

10 INPUT USING " " ,"ENTER CODE 3 ",X

20 SETCOM3 X :SET THE CODE

30 END


GETDELKEY

GETDELKEY ---------- Retrieves the decimal value of the key that causes the backspace sequence to be sent

Type

U/BL statement.

Syntax

GETDELKEY dest var

Arguments

dest var

A numeric variable into which the value of the key that causes the backspace sequence will be sent

Description

The GETDELKEY statement retrieves the decimal value of the key that causes the backspace sequence. The default value is 8.

The GETDELKEY statement is equivalent to the STMA 3,3 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the backspace key.

10 GETDELKEY X :RETRIEVE BACKSPACE KEY VALUE

20 PRINT "The value of the current" :PRINT THE VALUE

30 PRINT "Backspace key is" ;X


GETGUIOPT

GETGUIOPT ---------- Returns options from U/Gi to U/BL

Type

Windows Object Command

Syntax

GETGUIOPT(OPTION, VALUE$ [, STAT])

Arguments

OPTION | Specifies the information required
VALUE$ | Receives the requested information
STAT | Optional status return

Description

The GETGUIOPT statement returns information to U/BL on the state of U/Gi. The information requested is determined by the OPTION parameter:

0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
10 | 11 | 12 | 13 | 14 | 15 | 16-37 | 38 | 39 | 40
41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50
51 | 52 |  |  |  |  |  |  |  |

Note: The option numbers for the SETGUIOPT and GETGUIOPT statements do not match.

The possible settings for the OPTION parameter with the GETGUIOPT statement are:

Option

Description

0

Returns a string identifying the U/Gi revision, for example, 4.00

1

Returns the handle of the last Windows object to be activated. If no object is active, this option will return "–1"

2

Returns the U/Gi identification string, currently "WIN32" for the standard product and returns "AX32" if the U/Gi 32-bit ActiveX control is the client.

Earlier versions of U/Gi returned "WIN16". For example:

GETGUIOPT(2,A$,STAT)
IF STAT=0 THEN
  IF A$="AX32" THEN
  LET ISAX=1 \ ISUGI=0 \ UGI4=1 \ UGI3=0
  ELSE
  IF A$="WIN32" THEN
  LET ISAX=0 \ ISUGI=1 \ UGI4=1 \ UGI3=0
  ELSE
  LET ISAX=0 \ ISUGI=1 \ UGI4=0 \ UGI3=1
  END IF
  END IF
END IF

3

Returns the connection type in use; "SERIAL" or "TCP"

4

Returns the number of Windows object errors since the last call to this function

5

Returns the revision of the U/Gi to U/BL communication protocol currently in use. This can be used to determine what features are available using the current combination of U/BL and U/Gi.

6

Returns the TCP/IP hostname of the U/Gi client.

7

Returns the TCP/IP address of the U/Gi client.

8

Returns the ID of the Windows object that currently has focus. Returns "–1" if no Windows object is currently focus.

9

Returns the name of the current U/BL window.

10

Returns the client User ID (the user name with which the user is logged into Windows on the client PC).

11

Returns the current character height.

12

Returns the contents of the U/Gi title bar. This is usually the connection name and description at the top of the U/Gi Window.

13

Returns the name of the current U/Gi connection.

14

Returns "1" if the user has selected print preview from the Passthrough Printing preferences dialog box, otherwise returns "0"

15

Allows the program to determine when the user has exited Print Preview, and whether they exited using the Print or Close buttons. This guiopt can be polled to determine if the user is still in Print Preview. The possible return values are:

  • -1 - the user has never invoked Print Preview

  • 0 - the user has not exited Print Preview

  • 1 - the user exited via the CLOSE button without printing.

  • 2 - the user exited by printing the document

16-37

Reserved

38

Determine which font is currently being used for U/Gi printouts.

39

Determine the current header being used for U/Gi printouts. This consists of any string, which may be embedded with the following specially defined sequences:

%% Percentage sign
%p Current Page Number
%c Total Number of pages
%t Time (in local format)
%d Date (in local format)
%u Underline the header/footer text
%b Display the header/footer text in BOLD.
%i Display the header/footer text in italics.
%jl The header/footer text will be LEFT justified.
%jr The header/footer text will be RIGHT justified.
%jc The header/footer text will be CENTER justified.

40

Determine the current footer being used for U/Gi printouts. Footers use the same formatting sequences as headers (see above).

41

Determine the number of rows on a printed page from U/Gi

42

Determine the number of columns on a printed page from U/Gi

43

Establish the current orientation (portrait or landscape) of a printed page from U/Gi. The Syntax of the command is:

GETGUIOPT (43, ORIENT$[, STAT])

The default orientation is portrait (ORIENT$="0") with landscape mode being the option (ORIENT$="1").

44

Determine which of U/Gi's two modes for proportional font support is being used. The Syntax of the command is:

GETGUIOPT (44, PROP$[, STAT])

The default mode is to not use proportional spacing (PROP$="0") with the option being to use it (PROP$="1").

45

Reserved.

46

Determine the current destination of print passthrough output. The following values may be returned:

0 Direct to LPT1 on the client PC

1 Windows Printer Escapes

2 Windows Printer System

3 Print passthrough disabled

47

When using the Windows print system to output print passthrough, it is possible to request U/Gi to display a preview of the printed output before submitting the document to be printed. To determine whether the print preview option is currently set the GETGUIOPT 47, statement is used as follows:

GETGUIOPT (47, PREVIEW$[, STAT])

The default mode is not to preview the output (PREVIEW$="0") but this can be changed by calling the SETGUIOPT with PREVIEW$="1".

Note: This option only applies when U/Gi's print passthrough is being directed to the Windows Printer System. It is not available when either directly printing to LPT1 or when Windows Escapes are being used (or of course when print passthrough is disabled).

48

To allow user control over how a previewed document is printed, U/Gi can optionally display the 'Printer Options' dialog when the preview is closed. This allows the user to alter any of the printer configurations and re-preview the output using the new settings. Calling the GETGUIOPT 48 statement from a U/BL program allows you to determine if this option has been selected:

GETGUIOPT(48,ALTER$[, STAT])

ALTER$="1" if the dialog will be displayed on closing print preview, and "0" if it will not be displayed.

Note: This option only applies when U/Gi's print passthrough is being directed to the Windows Printer System and is to be previewed before printing.

49

When U/Gi is configured to allow the user to set the printing options from the preview (for instance if a SETGUIOPT (47,"1") has been issued), it may be preferable for the buffer to be cleared when the user exits the preview. U/Gi can be optionally configured to delete the contents of the passthrough buffer if the user cancels out of the print preview. Calling the GETGUIOPT 49 statement from a U/BL program allows you to determine if this option has been selected:

GETGUIOPT(49, CLR_BUF$[, STAT])

CLR_BUF$="1" if the buffer will be cleared, and "0" if the buffer will not be cleared.

Note: This option only applies when U/Gi's print passthrough is being directed to the Windows Printer System and is to be previewed before printing.

50

Returns the width, in pixels, of the monitor display screen.

51

Returns the height, in pixels, of the monitor display screen.

52

Returns the Windows version number in a string, which is formatted as follows:

MajorVersion.MinorVersion.PlatformId

For example, on Windows 2000:

* DIM value$[10]

* STAT=0

* GETGUIOPT(52,value$,STAT)

* ;value$

5.0.2

*

The version number can be used to infer the OS type:

OS | Major Ver | Minor Ver | PlatformID
Win95 | 4 | 0 | 1
Win98 | 4 | 10 | 1
WinME | 4 | 90 | 1
WinNT | 4 | 0 | 2
Win2000 | 5 | 0 | 2
WinXP | 5 | 1 | 2

See Also

SETGUIOPT


GETIKEY1

GETIKEY1 ---------- To retrieve the decimal value of the primary interrupt key

Type

U/BL statement.

Syntax

GETIKEY1 dest var

Arguments

dest var

A numeric variable that receives the value of the primary interrupt key

Description

The GETIKEY1 statement retrieves the decimal value of the primary interrupt key. The default value is 2. When this value is received by SuperDOS, it is not put in the ring buffer. Instead, the interrupt logic is invoked. See ON IKEY for a further explanation of the interrupt logic.

The GETIKEY1 statement is equivalent to the STMA 3,6 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the primary interrupt key.

10 GETIKEY1 X :RETRIEVE PRIMARY INTERRUPT KEY VALUE

20 PRINT "The value of the primary interrupt key is" ;X


GETIKEY2

GETIKEY2 ---------- Retrieves the value of the secondary interrupt key

Type

U/BL statement.

Syntax

GETIKEY2 dest_var

Description

The GETIKEY2 statement retrieves the decimal value of the secondary interrupt key. The default value is 3. When this value is received by U/BL, it is not put in the ring buffer. Instead, the interrupt logic is invoked and the SYS(10) flag is set to 1.

See ON IKEY for a further explanation of interrupt logic.

The GETIKEY2 statement is equivalent to the STMA 3,7 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

: This program retrieves the value of the secondary interrupt key

10 GETIKEY2 X :Retrieve secondary interrupt key value

20 PRINT "The value of the secondary interrupt key is "; X


GETINMAX

GETINMAX ---------- Retrieves the decimal value for the maximum number of characters allowed on INPUT

Type

U/BL statement.

Syntax

GETINMAX dest var

Arguments

dest var

A numeric variable into which the maximum number of characters allowed on INPUT are sent.

Description

The GETINMAX statement retrieves the decimal value of the number of the maximum number of characters allowed on INPUT. This is set to a default value of 132 whenever the U/BL prompt or password screen is displayed.

The GETINMAX statement is equivalent to the STMA 3,10 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the decimal value for the maximum number of characters allowed on input.

10 GETINMAX X :RETRIEVE MAX INPUT CHARACTERS

20 PRINT " There are currently "; X :PRINT THE VALUE

30 PRINT "characters allowed on INPUT."


GETLINECAN

GETLINECAN ---------- Retrieves the value of the line cancel character

Type

U/BL statement.

Syntax

GETLINECAN dest var

Arguments

dest var

A numeric variable into which the value of the line cancel character is returned

Description

The GETLINECAN statement retrieves the value of the key used to cancel an entire line. This is the decimal value that the line cancel key on the terminal sends to U/BL when that key is pressed. The default value is 127.

The GETLINECAN statement is equivalent to the STMA 3,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the line cancel key value.

10 GETLINECAN X :RETRIEVE THE LINE CANCEL KEY VALUE

20 PRINT X :PRINT THE VALUE

30 END


GETNUMBER

GETNUMBER ---------- Retrieve the numeric state of a Windows object

Type

Windows Object Command

Syntax

GETNUMBER(ID, VALUE [, STAT])

Arguments

ID | The unique handle of the Windows object
VALUE | Receives the object's numeric state
STAT | Optional status return

Description

The GETNUMBER command returns a number showing the state of a Windows object which can vary from object to object. For a combo box, dropdown combo box, list box or dropdown list, it is the index of the currently selected item (starting from 0). For check boxes and radio buttons it is the current on-off state. For objects where the current numeric state is undefined ,for instance where no item is selected in a list box or no numeric state can be associated with the object. For example, if the object is an edit boxes, a value of -1 will be returned.

Applies to

  • Check boxes

  • Combo boxes

  • Dropdown combo boxes

  • Dropdown lists

  • List boxes

  • Radio buttons.

Example

REM *** Create a combo box ****

COMBOBOX(1,5,5,5,40," Initial Selection | Line 1 | Line 2 ",32)

REM *** Allow the user to change things

REM *** Return the number

GETNUMBER(1,N)

PRINT "You selected <34>Line ",N+1,"<34>"

REM *** Clear up and return ****

DELETEWO(-1)

END

See Also

BUTTON

COMBOBOX

GETTEXT

LISTBOX

RADIOBUTTON

SETNUMBER


GETPROG

GETPROG ---------- Retrieves the name of the program that is currently running

Type

U/BL statement.

Syntax

GETPROG dest var[,task]

Arguments

dest var | A string variable into which the retrieved information is placed
task | An optional numeric expression containing a task number. If this argument is omitted, it will be assumed that the information to be retrieved is for the current task

Description

The GETPROG statement moves the name of the program that is currently running into the destination string. The maximum length of a program name is 12 bytes. If Data General compatibility is not in effect, (that is, the DGCOMP statement is set to OFF) and the program name is less than 12 bytes, the space after the program name is the destination string is filled with blanks. If DG compatibility is in effect (that is, DGCOMP is set to ON) and the program name is less than 12 bytes, the trailing blanks are truncated from the name, and the length of dest var is set accordingly. If the task specified is not signed on, the destination string is set to null.

The GETPROG statement is equivalent to the STMA 9,2 statement.

Possible Errors:

The BASIC error #-78 occurs if a task number is specified but is not a valid task number, that is, the task number is less than 1 or greater than the highest valid task number.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 9.


GETPRTKIND

GETPRTKIND ---------- Retrieves the decimal value of the current I/O port pass-through printer "kind"

Type

U/BL statement.

Syntax

GETPRTKIND dest var

Arguments

dest var

A numeric variable into which the value of the current I/O port pass-through printer "kind" will be sent.

Description

The GETPRTKIND statement retrieves the new value for the current I/O port pass-through printer "kind".

It is equivalent to the STMA 3,19 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the current pass-through printer "kind".

10 GETPRTKIND X :RETRIEVE PASS-THROUGH PRINTER KIND

20 PRINT "The value of the pass "; :PRINT THE VALUE

30 PRINT "through printer kind for the current I/O port is" ;X


GETQUEUE

GETQUEUE ---------- Moves a seven-byte string from the current task into dest var

Type

U/BL statement.

Syntax

GETQUEUE dest var[,task]

Arguments

dest var | A string variable into which the retrieved information is placed
task | An optional numeric expression containing a task number. If this argument is omitted, it will be assumed that the information to be retrieved is for the current task

Description

The GETQUEUE statement moves the 7 bytes that were set by the SETQUEUE statement (or STMA 10,1). This is usually used to get the default output device. For example, a menu program can ask the user to specify which printer is the default. The user's response is put into memory via. SETQUEUE (or STMA 10,1). After that, all the programs that are run can find out what the default printer is by using GETQUEUE. The value set by SETQUEUE (or STMA 10,1) is not reset automatically when returning to the U/BL prompt or the password screen. If the task specified is not signed on, the destination string is set to null.

The GETQUEUE statement is equivalent to the STMA 9,3 statement.

Possible Errors

If a task number is specified but is not a valid task number (that is, the task number is less than 1 or greater than the highest valid task number), the BASIC error #-78) occurs.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See STMA 9.


GETREC

GETREC ---------- Get an available record from a DG format linked-available file

Type

U/BL statement or command

Syntax

GETREC filenum,recnum

Arguments

filenum | A numeric expression representing either the number of an LOPENed data file or if BBEXTENSION=SDOS, the channel on which the file is open..
recnum | A numeric variable which receives the number of an available record, or -1 if the data file is full.

Description

The GETREC command returns the next available record number from aDG format linked-available-record file. If there are any deleted records in the file, the GETREC command returns a deleted record number and updates the deleted record chain. If no deleted records exist, the GETREC command returns the next unused record in the file and updates the next available record pointer. If the file is full, a record number of -1 is returned. Refer to the BBDELREC environment variable for further information on the deleted record chain.

Record 0 of linked-available-record files is reserved for U/BL to maintain details of the deleted record chain and next available records. The GETREC command locks record 0 during its execution using the filename supplied in the LOPEN statement.

If you want the Linked Available Files control information to be stored in the files FCB area, and a separate record 0 control record to not be maintained, when using the GETREC statement, set the BBNEWRECZERO environment variable to 'N' .

Example

The files are open, strings are dimensioned and the name of a new customer is in CUSTKEY$:

00075 LET FINDKEY$=CUSTKEY$ : USE COPY OF CUSTKEY$ IN KFIND

00080 KFIND 1,BUF$,FINDKEY$,RECNO

00090 IF RECNO>0 THEN : CUSTOMER ALREADY ON FILE

00100 PRINT "Customer already on file"

00110 ELSE

00115 GETREC 2,RECNO

00120 IF RECNO=-1 THEN : FILE FULL

00130 PRINT "Sorry, file is full"

00140 STOP

00150 END IF

00160 GOSUB 1000 : FORMAT CUSTOMER RECORD

00200 LWRITE FILE [2,RECNO], CUSTREC$

00210 KADD 1,BUFF$,CUSTKEY$,RECNO

00220 IF RECNO THEN PRINT "Customer added"

00230 END IF

See also

BBDELREC

BBNEWRECZERO


GETRNO

GETRNO ---------- Returns the next available record number in a U/BL linked-available data file

Type

U/BL statement.

Syntax

GETRNO (chan,recno)

Arguments

chan | A numeric expression specifying the channel number on which the file was OPENed.
recno | A numeric variable which will receive the next available record number.

Description

The GETRNO statement returns the next available record number in a U/BL linked-available data file.

The statement first checks the "next-available-record-number" field in the FCB. If there any deleted records available, the "first-deleted-reco rd-number" in the chain is returned. If there are no deleted records available, the record number returned is one greater than the highest record number used. If the highest record number used is greater or equal to the maximum record number before it is incremented, a run-time error occurs.

The number of active records field, the last record number field, and the first deleted record number field are all update by the GETRNO statement. Therefor if a program decides after a GETRNO statement not to update that record with an active record, the program should make the record available for re-use. This is done by REWRITing a dummy record with a valid status byte and the RDELing the record.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

:

00180 GETRNO (1,RNO)

:

See also

GETREC


GETSEA

GETSEA ---------- Returns the searchlist for the current task

Type

U/BL statement.

Syntax

GETSEA list$

Arguments

list$

A string variable to receive the search that must be DIMensioned to at least 12 bytes.

Description

The GETSEA statement retrieves all the drive and user group combinations in the searchlist of the current task. Each two bytes contain a drive number in byte one and a user group in byte two. The first drive and user group combination is the default drive and user group. Since there are six possible drive and user group combinations in the searchlist, the string variable must be DIMensioned to at least 12 bytes.

The GETSEA statement returns 12 bytes of data in the list$ argument. If any of the pairs of bytes are <0><0>, that pair and any following pairs are not part of the searchlist, that is, a drive and user group of 0:0 signals the end-of-list.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This example demonstrates the use of the GETSEA statement. It retrieves and displays the current task's searchlist.

10 DIM X$ (12) ,Y$ (80) :Init

20 GETSEA X$ :Get searchlist

30 Y$="SEARCHLIST IS " :Init display

40 FOR I=1 TO 6 :Loop to extract searchlist

50 D=ASC (X$ (I*2 -1, I*2 -1)) :Get drive

60 G=ASC (X$ (I*2, I*2)) :Get user group

65 IF D=0 & G=0 THEN I=6 \ GOTO 85

70 Y$ (0)=D, ":" ,G :Append to display

80 IF I<6 THEN Y$ (0)=", " :Append delimiter

85 NEXT I :End loop

90 PRINT \ PRINT Y$ :Displays searchlist

95 END


GETSWAPLEV

GETSWAPLEV ---------- Retrieves the current swap level

Type

U/BL statement.

Syntax

GETSWAPLEV dest var

Arguments

dest var

A numeric variable into which the value of the referenced item is moved

Description

The GETSWAPLEV statement retrieves the current swap level.

It is equivalent to the STMA 3,11 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See STMA 3 & 4.


GETSYSBITS

GETSYSBITS ---------- Retrieves the system flag bits that affect how the primary unpend key is treated

Type

U/BL statement.

Syntax

GETSYSBITS dest var

Arguments

dest var

A numeric variable into which the value of the referenced item is moved

Description

The GETSYSBITS statement retrieves the information in the system flags Bit 0 and Bit 1.

These flags have the following effect:

Bit 0

If bit 0 is set to 1 and input is being taken at the one-character-at-a-time rate, then the primary unpend or <return> key, (CHR$(13)), is not placed in the INPUT string. This is compatible with Data General.

If bit 0 is set to 0, every character encountered is put in the INPUT string. This is the default.

Bit 1

If bit 1 is set to 1, the primary unpend typed in the first position of an @INPUT field keeps the field intact just as if the secondary unpend key had been entered. The primary unpend in any position still blanks the remainder of the field.

If bit 1 is set to 0, the primary unpend character in the first position of an @INPUT field blanks the entire field. This is the default.

It is equivalent to STMA 3,18.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 3,4.


GETTABSZ

GETTABSZ ---------- Retrieves the decimal value of the number of spaces between tab stops

Type

U/BL statement.

Syntax

GETTABSZ dest var

Arguments

dest var

A numeric variable into which the number of spaces between tabstops will be sent.

Description

The GETTABSZ statement retrieves the decimal value of the number of spaces between tab stops. This value is used when executing a PRINT statement using commas rather than semi-colons as field delimiters. The default value is 0.

The GETTABSZ statement is equivalent to the STMA 3,9 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

The following program prints the decimal value for the number of spaces between tab stops.

10 GETTTABSZ X : Retrieve the Tab space value

20 PRINT "There are currently ", X; : Print the value

30 PRINT "spaces between tabs."


GETTEXT

GETTEXT ---------- Retrieves the textual state of a Windows object

Type

Windows Object Command

Syntax

GETTEXT(ID, TEXT$ [, STAT])

Arguments

ID | The unique handle of the Windows Object
TEXT | Receives the textual state of the object
STAT | Optional status return

Description

The GETTEXT command returns the text, currently associated with the Windows Object identified by the ID handle, in the TEXT$ parameter. This varies from object to object. For example, for an edit box it is the text in the box itself. For a combo box, dropdown combo box; list box or dropdown list, it is the text of the currently selected item. For buttons, combo boxes and radio buttons it is the current label (or bitmap name for bitmap buttons).

Applies to

  • Buttons

  • Check boxes

  • Combo boxes

  • Dropdown combo boxes

  • Dropdown lists

  • Edit boxes

  • List boxes

  • Radio buttons

Example

DIM NAME$[100], ADDRESS1$[100], ADDRESS2$[100]

REM *** Create the edit boxes ****

EDITBOX(1,5,5,1,40,"Name",0)

EDITBOX(2,7,5,1,40,"Address 1",0)

EDITBOX(3,8,5,1,40,"Address 2",0)

REM *** Allow the user to enter some details ****

REM *** Get the changed text ****

GETTEXT(1,NAME$)

GETTEXT(2,ADDRESS1$)

GETTEXT(3,ADDRESS2$)

PRINT @(10,10);"Name:",NAME$

PRINT @(11,10);"Name:",ADDRESS1$

PRINT @(12,10);"Name:",ADDRESS2$

REM *** Clear up and return ****

DELETEWO(-1)

END

See Also

BUTTON

COMBOBOX

EDITBOX

GETNUMBER

LISTBOX

RADIOBUTTON

SETNUMBER

SETTEXT


GETTYPE

GETTYPE ---------- Retrieves terminal type

Type

U/BL statement.

Syntax

GETTYPE dest var

Arguments

dest var

A numeric variable into which the value of the terminal type is returned.

Description

The GETTYPE statement moves the value of the terminal type into dest var. Terminal type is a digit (1, 2, 3, or 4).

It is equivalent to the STMA 1,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program performs a SWAP to the program below which sets the terminal type.

10 SWAP "B" :RUN PROG B TO SET CODE

20 GETTYPE X :GET TERMINAL TYPE

30 PRINT X :PRINT TERMINAL TYPE

40 END

Program "B" gets the terminal type from the user and sets it.

10 INPUT USING " ", "ENTER TERMINAL TYPE " ,X

20 SETTYPE X :SET TERMINAL TYPE

30 END


GETUNPEND1

GETUNPEND1 ---------- Retrieves the decimal value of the primary unpend character

Type

U/BL statement.

Syntax

GETUNPEND1 dest var

Arguments

dest var

A numeric variable into which the value of the primary unpend character will be sent.

Description

The GETUNPEND1 statement retrieves the value of the key that performs the primary unpend. An unpend character terminates an INPUT statement. When a program ends and returns to the U/BL prompt or the password screen, the primary unpend is set to the default value of 13 (carriage return).

The GETUNPEND1 statement is equivalent to the STMA 3,4 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the primary unpend character.

10 GETUNPEND1 X :RETRIEVE PRIMARY UNPEND CHARACTER

20 PRINT "The value of the primary" :PRINT THE VALUE

30 PRINT "Unpend character is"; X


GETUNPEND2

GETUNPEND2 ---------- Retrieves the decimal value of the secondary unpend character

Type

U/BL statement.

Syntax

GETUNPEND2 dest var

Arguments

dest var

A numeric variable into which the value of the primary unpend character will be sent

Description

The GETUNPEND2 statement retrieves the value of the key that performs the secondary unpend. An unpend character terminates an INPUT statement. When a program ends and returns to the U/BL prompt or the password screen, the secondary unpend is set to the default value of 10 (line feed).

The GETUNPEND2 statement is equivalent to the STMA 3,5 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the secondary unpend character.

10 GETUNPEND2 X :RETRIEVE SECONDARY UNPEND CHARACTER

20 PRINT "The value of the secondary" :PRINT THE VALUE

30 PRINT "Unpend character is"; X


GETUNPEND3

GETUNPEND3 ---------- Retrieves the decimal value of the unpend character 3

Type

U/BL statement.

Syntax

GETUNPEND3 dest var

Arguments

dest var

A numeric variable into which the value of the unpend character 3 will be sent.

Description

The GETUNPEND3 statement retrieves the value of the key that performs an unpend using upend character 3. An unpend character terminates an INPUT statement. When a program ends and returns to the U/BL prompt or the password screen, the unpend character 3 is set to no default (255).

The GETUNPEND3 statement is equivalent to the STMA 3,16 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the unpend character 3.

10 GETUNPEND3 X :RETRIEVE UNPEND CHARACTER 3

20 PRINT "The value of unpend character 3" :PRINT THE VALUE

30 PRINT "Unpend character is"; X


GETUNPEND4

GETUNPEND4 ---------- Retrieves the decimal value of the unpend character 4

Type

U/BL statement.

Syntax

GETUNPEND4 dest var

Arguments

dest var

A numeric variable into which the value of the unpend character 4 is sent

Description

The GETUNPEND4 statement retrieves the value of the key that performs an unpend using unpend character 4. An unpend character terminates an INPUT statement. When a program ends and returns to the U/BL prompt or the password screen, the unpend character 4 is set to no default (255).

The GETUNPEND4 statement is equivalent to the STMA 3,17 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program retrieves the value of the unpend character 4.

10 GETUNPEND4 X :RETRIEVE UNPEND CHARACTER 4

20 PRINT "The value of unpend character 4" :PRINT THE VALUE

30 PRINT "Unpend character is"; X


GETXTRAINF

GETXTRAINF ---------- Returns the state of an ActiveX control

Type

U/BL statement.

Syntax

GETXTRAINF(ID,2,LIC$)

Arguments

ID | The handle of the ActiveX control
LIC$ | The license string.

Description

Many ActiveX controls can present a user interface to allow program designers to configure the control. This is usually in the form of a series of property sheets that control how the control works. These property sheets can be displayed by calling SETXTRAINF(ID,1,"") on the control.

After the control has been configured in this manner, its state can be retrieved from a control, stored into a string and re-used when the control is created to restore the state immediately. The state is retrieved by using the GETXTRAINF(ID,1) call, and the resulting string is passed into the AXCREATE statement. For example:

REM * Create control, show property sheets and store data *

DIM Z$[10000]

AXCREATE(1,5,5,10,40,"","MSCAL.Calendar","",1,STAT)

REM * Show the properties *

SETXTRAINF(1,1,"")

INPUT A

REM * Get the configuration data *

GETXTRAINF(1,1,Z$)

PRINT Z$

REM * Recreate the control as it was stored *

DIM Z$[10000]

REM * Tag to indicate the following is data *

Z$="DATA:"

REM * Replace this with the data from the GETXTRAINF call *

Z$[0]="A01234CD516829399432491020EDBA2321732173392392199"

Z$[0]="BACD516829399432491020EDBA2321732173392392199"

AXCREATE(1,5,5,10,40,"","MSCAL.Calendar",Z$,1,STAT)

This license string can be generated on a licensed machine by using the GETXTRAINF(ID,2) statement against the control as follows:

DIM LIC$[100]

AXCREATE(1,5,5,10,40,"","My.LicensedControl","",1,STAT)

GETXTRAINF(ID,2,LIC$)

PRINT LIC$


GOSUB

GOSUB ---------- Temporarily branches to a subroutine

Type

U/BL statement

Syntax

GOSUB line_ref

...

RETURN

Arguments

line_ref

Any valid line number or label in the program.

Description

A GOSUB statement results in the program executing a subroutine. A subroutine is a portion of code which may be executed from any part of a program. When a RETURN statement is encountered in the subroutine, the program resumes from the statement following the one at which the subroutine was called.

A subroutine may contain more than one RETURN statement. However, an error occurs if a RETURN statement is encountered without an active GOSUB statement. A subroutine may be called any number of times in a program, and one subroutine may be called from within another subroutine. Such nesting of subroutines is limited to 22.

If the first line in a subroutine (the one referenced by the GOSUB statement) is a REM statement, the contents of the REM are placed as a comment to the GOSUB statement unless the GOSUB statement already has a comment. This provides documentation for the GOSUB statement.

As all variables in a program are global, it is not possible to explicitly pass parameters to a subroutine. The subroutine may create, test or modify any variables in the program.

The GOSUB stack can be reset using the STMA 8,2 statement.

Example

* list

00005 PRINT "In the mainline"

00010 GOSUB 00100 : First subroutine

00020 PRINT "Back in the mainline"

00030 GOSUB 00200 : Second subroutine

00040 PRINT "Mainline finishing now"

00050 END

00100 REM First subroutine

00110 PRINT "This is the first subroutine executing"

00120 PRINT "This is the first subroutine ending"

00130 RETURN

00200 REM Second subroutine

00210 PRINT "This is the second subroutine executing"

00220 GOSUB 00100 : First subroutine

00230 PRINT "This is the second subroutine ending"

00240 RETURN

* run

In the mainline

This is the first subroutine executing

This is the first subroutine ending

Back in the mainline

This is the second subroutine executing

This is the first subroutine executing

This is the first subroutine ending

This is the second subroutine ending

Mainline finishing now

See also

ON GOSUB

REM

RETURN

STMA 8


GOTO

GOTO ---------- Branches out of the normal program sequence to a specified line

Type

U/BL statement

Syntax

GOTO line_ref

Arguments

line_ref

Any valid line number or label in the program.

Description

A GOTO line_ref statement results in program execution continuing from that statement, so long as the statement at line_ref is executable, that is, it is not a REM, DATA or RFORM statement. If the statement is not executable, program execution continues from the next executable statement following line_ref. If line_ref does not exist, error 13 - "Line Number" - occurs.

If line_ref is a REM statement, the contents of the REM are placed as a comment to the GOTO statement unless the GOTO already has a comment. This provides documentation for the GOTO statement.

If a GOTO statement refers to its own line_ref then an infinite loop will result.

The use of the GOTO statement is not recognized as good programming practice. Block IF statements, and DO WHILE loops should be used instead where possible.

Example

* list

00010 RANDOMIZE

00012 PRINT "I'll think of a number - you try to guess it"

00020 LET X=RND(100)+1

00030 INPUT USING "","Enter your guess..",GUESS

00040 LET ATTEMPTS=ATTEMPTS+1

00050 IF GUESS=X THEN

00060 PRINT "You got it in ";ATTEMPTS;" tries."

00065 ATTEMPTS=0

00070 PRINT "Now I'm thinking of another number"

00080 GOTO 00020

00090 ELSE

00100 IF GUESS>X THEN PRINT "Too high" ELSE PRINT "Too low"

00110 GOTO 00030

00120 END IF

* run

I'll think of a number - you try to guess it

Enter your guess..45

Too high

Enter your guess..30

Too low

Enter your guess..34

Too high

Enter your guess..32

You got it in 4 tries.

Now I'm thinking of another number

Enter your guess..

See also

DO WHILE

IF

LOOP

ON_GOTO

REM


GPOS

GPOS ---------- Returns the current file position

Type

U/BL function

Syntax

GPOS (channel)

Arguments

channel

A numeric expression representing the channel number of an open file

Description

The GPOS function returns the byte at which the file pointer is positioned. The file pointer is positioned by any file access. If a file is not open, the GPOS function returns -1. The GPOS function must not be used after a BLOCK READ FILE or BLOCK WRITE FILE as these commands leave the file pointer position undefined.

Example

* list

00010 REM Find the size of any file

00020 DIM FILENAME$[64]

00030 INPUT USING "","Enter file name...",FILENAME$

00040 IF FILENAME$="" THEN GOTO 00999

00050 OPEN ERROR, FILE[1,13],FILENAME$

00060 IF ERROR THEN

00070 PRINT "Can't open ";FILENAME$

00080 ELSE

00090 POSITION FILE[1,-1] : position to end of file

00100 PRINT "The file size is ";GPOS(1)

00110 CLOSE FILE[1]

00120 END IF

00130 GOTO 00030

00999 END

* run

Enter file name...cust.udb

The file size is 25626

Enter file name...nofile

Can't open nofile

See also

BLOCK READ FILE

BLOCK WRITE FILE

$F

READ FILE

WRITE FILE


GUIX

GUIX ---------- Support U/Gi extensions

Type

U/BL command and statement

Syntax

GUIX (func_code, param_string, stat)

Arguments

func_code | The numeric function code of the required GUI extension
param_string | A string containing any parameters required by the GUI extension. The Parameters are strings separated by semicolons ';'. A semicolon is also required at the end of the last parameter.
stat | An optional numeric variable that returns the status of the GUIX call. A return value of zero indicates the call was successful.

Description

The GUIX statement (can be prefixed with an optional '_', for example, GUIX in U/BL) supports U/Gi extensions. To be able to use these extensions you must be running U/BL in GUI mode.

The GUIX statements currently supported by U/BL are:

  • 90-91 - Binary file transfer

  • 70 - ASCII file transfer

  • 60 - Displaying of bitmap pictures

  • 61-62 - Playing sound wavefiles

  • 80, 84 - Automatic copy of text to the Windows clipboard

  • 82 - Launching other Windows applications from U/BL

  • 83 - Terminating U/Gi from U/BL

  • 81, 93 - Dynamic Data Exchange Messages

Binary (z-modem) File Transfer

To transfer a file (binary or ASCII), for example, a DIF file, from the UNIX server to the PC, make the following GUIX call:

GUIX(90, "SrcFile;DestFile;", stat)

The numeric function code argument, func_code, must be set to 90 for file transfer. The param_string argument contains the following parameters:

SrcFile | The source file on the UNIX host. The full UNIX path should be specified.
DestFile | The destination file on the PC. If a full path name is not specified then the file will be transferred to the current directory.

Note: For U/BL under UNIX the rz and sz utilities must be accessible for U/BL to run.

Example

Transfer the DIF file, test.dif, on the UNIX server in directory /u/data to the PC, as file TMP.DIF, to the directory C:\EXCEL.

REM ASCII File Transfer

GUIX(90,"/u/data/test.dif;C:\EXCEL\TMP.DIF;",stat)

A second function allows you to transfer a file from the PC to the UNIX server. The same conditions, as above, apply. Making the following GUIX call from U/BL transfers the file from the PC to the UNIX host:

GUIX(91, "SrcFile;", stat)

The numeric function code argument, func_code, must be set to 91. The param_string argument contains just one parameter:

SrcFile

The source file on the PC. The file is transferred into the current directory in UNIX with the same file name.

For reliable communication links between U/BL and U/Gi (for instance if connecting over TCP/IP) the FILETRANSFER statement provides better performance as it does not have its own in built error correction.

ASCII File Transfer

This function has been superceded by GUIX 90 and 91. It has been retained only for backwards compatibility. If you need to use file transfer you should use the z-modem functions which offer much greater flexibility and speed.

To transfer an ASCII file, for example, a DIF file, from the UNIX server to the PC make the following GUIX call:

GUIX(70, "SrcFile;DestFile;", stat)

The numeric function code argument, func_code, must be set to 70 for ASCII file transfer. The param_string argument contains the following parameters:

SrcFile | The source file on the UNIX host. The full UNIX path should be specified.
DestFile | The destination file on the PC. If a full path name is not specified then the file will be transferred to the current directory.

Note: The text file must not contain any semi-colons ';'.

Example

Transfer the DIF file, test.dif, on the UNIX server in directory /u/data to the PC, as file TMP.DIF, to the directory C:\EXCEL.

REM ASCII File Transfer

GUIX(70,"/u/data/test.dif;C:\EXCEL\TMP.DIF;",stat)

Displaying Bitmaps

The bitmap file must be of type '.BMP' or '.DIB' and must exist on the PC, that is, not on the host computer. To display a bitmap on the PC make the following GUIX call from U/BL:

GUIX(60, "title;filename;x;y;width;height;initial display;coordinate mode",stat)

The bitmap will appear in a window on the PC. The numeric function code argument, func_code, must be set to 60 for the display of bitmaps. The param_string argument contains the following parameters:

title | The text to display on the title bar of the window that the picture will appear in. This is a mandatory entry as you will have no way of deleting the bitmap.
filename | The full pathname of the bitmap file on the PC including the '.BMP' or '.DIB' extension. If a full pathname is not used, then U/Gi will search for the bitmap in the following directories: The current (PC) directory, \windows, the DOS PATH.
x , y | Define, in screen (pixels) or character coordinates (see coordinate mode, below. Pixel coordinates are relative to the upper left of the Windows desktop, character coordinates relative the U/Gi window.
width , height | Define, in screen or character coordinates, the size of the picture. If you use values of zero then the picture is displayed in its "natural" size. If you use non-zero values then the picture is scaled to fit.
initial display | Determines whether the bitmap will be initially displayed minimized, maximized or with the dimensions specified by width and height. A value of zero shows the bitmap with the specified dimensions. 1 shows the bitmap minimized as an icon; 2 shows the bitmap maximized to fill the whole PC screen. This parameter is optional. The default value is zero.
coordinate mode | Determines whether the values you give for the bitmap's position and size are in terms of screen coordinates or character coordinates. A value of zero specifies screen coordinates, 1 character coordinates. Note that screen coordinates are not device independent. A position of 100,100 on an VGA monitor will not be the same on an SVGA monitor, whereas 5,5 in character mode will place the bitmap in the sample position relative to the U/Gi window on both monitors. This parameter is optional. The default is zero; screen coordinates.

Removing Bitmaps

To remove a bitmap from display, the U/BL windows delete statement is used, as follows:

WDELETE("title")

title is the text displayed on the title bar of the window of the bitmap.

Example

Display a bitmap called LEAVES.BMP from the directory C:\WINDOWS. Give the window a title of "My Pix". Display the picture at position 10,20 in its natural size.

REM Display a bitmap

GUIX(60,"MyPix;C:\WINDOWS\LEAVES.BMP;10;20;0;0;",stat)

Since the bitmap exists in one of the directories that U/Gi will search automatically, the full path need not have been specified, for example:

REM display a bitmap

GUIX(60, "My Pic;LEAVES.BMP;10;20;0;0;", stat)

To remove the bitmap:

WDELETE("My Pic")

Setting Bitmap Style

The GUIX 85 statement, allows you to control the style of the bitmaps you display when you use GUIX 60.

GUIX (85, "style1;style2;...", stat)

As well as several native Windows styles U/Gi also supplies three pre-defined styles.

You can apply the following styles to a bitmap. The first three are the most common combinations of styles defined for convenience. BORDER_AND_TITLE is the default if no style is specified before a bitmap is displayed.

BORDER_AND_TITLE | Displays the bitmap with a resizable border, a title bar, maximize and minimize buttons.
BORDER_NO_TITLE | Displays the bitmap with a resizable border
PICTURE_ONLY | Displays the bitmap with no border. Useful for drawing logos, etc. on forms
WS_CAPTION | Displays the bitmap with a title
WS_BORDER | Adds a border, which cannot be resized
WS_THICKFRAME | Adds a resizable border
WS_MINIMIZEBOX | Adds a minimize button
WS_MAXIMIZEBOX | Adds a maximize button
WS_POPUP | The bitmap can be moved if it has a border.

For example:

GUIX (85, "PICTURE_ONLY;", STAT)

Playing Sound Wavefiles

To play wave files on the PC:

  • The wave file must be of type '.WAV' and must exist on the PC, that is, not on the host computer.

  • You must have a 'Sound Blaster' compatible card and speakers installed on your PC. Make sure the card works by using the sounds supplied with the card.

Make the following GUIX call from U/BL and the sound will be played:

GUIX(61,"filename;",stat)

The numeric function code argument, func_code, must be set to 61 to play of soundwaves. The param_string argument contains the following parameter:

filename

The full pathname of the wave file on the PC including the '.WAV' extension. If a full pathname is not used, then U/Gi will search for the wave file in the following directories: The current (PC) directory, \windows, the DOS PATH.

Note: The semicolon ';' at the end of the parameter string.

Only one sound can be played at a time. Starting a new sound will stop the currently playing sound and start the new one.

Stopping a Soundwave

This is achieved by the following statement:

GUIX(62,";",stat)

As you can have only one soundwave file playing at a time, it is not necessary to specify the soundwave name. For example:

Play the sound CHIMES.WAV from the directory C:\WINDOWS.

REM Play the chimes

GUIX(61, "C:\WINDOWS\CHIMES.WAV;", stat)

DELAY 30

GUIX(62, ";", stat)

Automatic Copy of Text to Windows Clipboard

An area of text from the current U/BL window can be copied to the Windows clipboard. This call duplicates the function of the Edit menu Copy option. This function would not be usually used alone, but in conjunction with the GUIX 81 statement. The contents of the Windows clipboard can then be automatically pasted into other Windows applications via DDE Dynamic Data Exchange messages (see below).

To action an automatic copy make the following GUIX call from U/BL:

GUIX(80,"upRow;leftCol;botRow;rightCol;",stat)

The numeric function code argument, func_code, must be set to 80 to do a copy. The param_string argument contains the following parameters:

upRow | Defines the upper row of the selected text within the current U/BL window.
leftCol | Defines the left column of the selected text within the current U/BL window.
botRow | Defines the bottom row of the selected text within the current U/BL window.
rightCo | Defines the right column of the selected text within the current U/BL window.

The top left corner of the U/BL window is always row 1 and column 1, regardless of where the window is on the Terminal Emulator Window.

Example

To copy the area of the current U/BL window described by row 5 to row 10 and column 8 to column 45.

GUIX(80, "5;8;10;45;", stat)

Automatic Copy of Table to Windows Clipboard

An area of text from the current U/BL window can be copied to the Windows clipboard formatted as a table. This call duplicates the function of the Edit menu Copy Table option. This function would not be usually used alone, but in conjunction with the GUIX 81 statement. The contents of the Windows clipboard can then be automatically pasted into other Windows applications via DDE Dynamic Data Exchange messages (see below). This function is particularly useful when pasting data into spreadsheets such as Microsoft Excel.

Make the following GUIX call from U/BL:

GUIX(84,"upRow;leftCol;botRow;rightCol;",stat)

The numeric function code argument, func_code, must be set to 84 for the conversion. The param_string argument contains the following parameters:

upRow | Defines the upper row of the selected text within the current U/BL window.
leftCol | Defines the left column of the selected text within the current U/BL window.
botRow | Defines the bottom row of the selected text within the current U/BL window.
rightCo | Defines the right column of the selected text within the current U/BL window.

The top left corner of the U/BL window is always row 1 and column 1, regardless of where the window is on the Terminal Emulator Window.

Note: This functionality works correctly when pasting a table directly into Microsoft Word, but does not work correctly when pasting into Microsoft Word Tables.

Example

To copy the area of the current U/BL window described by row 5 to row 10 and column 8 to column 45.

GUIX(84, "5;8;10;45;", stat)

Launch Windows Applications from U/BL

You can launch other Windows applications from within U/BL. This GUIX call takes two parameters: the name of the application program to run and the 'activation code'. This code specifies how Windows will run and displays the application.

To launch a Windows application make the following GUIX call from U/BL:

GUIX(82, "winApps;code;", stat)

The numeric function code argument, func_code, must be set to 82 to launch a Windows application. The param_string argument contains the following parameters:

winApps

The full pathname of the Windows application including the '.exe' extension . If a full pathname is not used, then U/Gi will search for the application in the following directories: The current (PC) directory, \windows, the DOS PATH.

code

Values from 1 to 10, where:

Code | Action
1 | Activates and shows the application as it was last saved
2 | Activates the application and shows it minimized as an icon
3 | Activates the application and shows it maximized
4 | Shows the application window but the current window that is active (normally U/Gi) will remain active
5 | Not used
6 | Minimizes the application
7 | Displays an application as an icon, but the current window that is active remains active
8 | Displays the application as it was last saved, but the current window that is active remains active
9 | Not used
10 | Returns in stat: 0 (zero) if application is already launched 1 if application is not already launched
30 | Activates the application as modal. The U/BL session will wait for the application to finish before control is given back to the program.

Note: When an application is 'activated' it is made the front window and given the input focus. Usually you will use code 1 to launch and use the application. If you want to invoke an application and display it as an icon but keep U/Gi as the active application you would use code 7.

Example

To run the Windows notepad editor, NOTEPAD.EXE:

GUIX(82, "c:\windows\notepad.exe;1;", stat)

Note: The semicolon ';' at the end of the application path.

Terminating U/Gi from U/BL

You can terminate and close the U/Gi application from within U/BL by making the following GUIX call from U/BL:

GUIX(83, ";", stat)

The numeric function code argument, func_code, must be set to 83 to close U/Gi from within U/BL.

Note: The semicolon ';' in the parameter string is required.

Dynamic Data Exchange Messages

You can send DDE Dynamic Data Exchange messages from U/Gi to other Windows applications. DDE is a complex subject and it is beyond the scope of this manual to describe it. For a description of the DDE messages it will respond to refer to the Windows application's documentation to which you wish to send messages, for example, Microsoft Word for Windows, Excel.

U/Gi supports two modes of DDE

  • Execute - Run macro or menu commands.

  • Poke - Poke commands allow you to directly enter data into other applications as if they were typed from the keyboard.

The Windows application must already be running otherwise an error message will appear and a non-zero status will be returned by the U/BL DDE message. To check whether it is running you can perform an GUIX 82 statement, with code 10, which if stat returns 0 means the application is running. Then perform another GUIX 82 (see below) to launch the application prior to sending the DDE message.

To send a DDE message perform the following steps:

  • You must be logged into the host through U/Gi.

  • You must start U/BL with the '-g' switch:

ubl -g

  • Make one of the following GUIX call from U/BL:

DDE Execute

GUIX(81,"DDEserver;topic;message;",stat)

81 is the numeric function code required for DDE execute messages.

DDEserver | The name of the DDE server or target application, for example, Microsoft Word or Excel.
topic | The topic of the DDE message.
message | The message that instructs the server or target application what to do.
stat | An optional numeric variable that on return will contain the status of the GUIX call. Zero indicates success.

Here follow two examples.

1. DDE Message to Word for Windows

One very powerful DDE message allows you to paste the contents of the Windows clipboard into Microsoft Word for Windows. Used in conjunction with the GUIX 80 'Copy' statement, this allows you to automatically paste output from your U/BL application into Word without any user intervention.

GUIX(81, "WINWORD;System;[EditPaste];", stat)

In this example, the server is WINWORD, the topic System and the message instructs Word to execute the EditPaste macro. This general template can be used to execute any Word macro.

2. DDE Message to Excel

Assume you want to automatically load a DIF file created by your UNIX application and transferred to the PC by the U/BL GUIX 70 statement into Microsoft Excel, reformat the columns, sum a particular column and print it out. This can be achieved by first recording manually a macro, say UBLMACRO, in Excel that performs these tasks. Remember to use the Macro Run option in Excel to check that it runs correctly. Excel may prefix the macro name with some other text so check the exact name of the macro when you run it. Typically, Excel will place Macro1! in front of your macro name, giving in this case Macro1!UBLMACRO.

In U/BL you would use the following DDE message to run your macro:

GUIX(81,"EXCEL;System;[Run(<34>Macro1!UBLMACRO<34>)];", stat)

The server is EXCEL, the topic System and the message is [Run("Macro1!UBLMACRO")]. Note that <34> is used in the command to enclose the macro name in double quotes.

Refer to your Excel User Manual for further details on creating macros and the use of DDE messages.

DDE Poke

GUIX(93,"DDEserver;topic;item;data;",stat)

93 is the numeric function code required for DDE poke messages.

DDEserver | The name of the DDE server or target application, for example, Microsoft Word or Excel.
topic | The topic of the DDE message.
item | The position in the target application,for example, a cell in a spreadsheet.
stat | An optional numeric variable that on return will contain the status of the GUIX call. Zero indicates success.

Example

DDE poke into Excel. To enter the value 123.45 into the cell R1C2 of an Excel spreadsheet, Sheet1, you could use the GUIX command:

GUIX (93, "EXCEL;Sheet1;R1C2;123.45;", stat)


$H

$H ------------ Display the contents of the specified string variable

Type

U/BL command.

Syntax

$H var$ [base]

Arguments

var$ | A string variable
base | The base in which the contents of the string are to be displayed.

Description

The $H command displays the contents of string variable specified. The default base is 16 (hexadecimal). The second parameter can be used to specify a new base. This new base will then become the default for subsequent $H commands. If an invalid bbase, for example, 7 is used, the $H command ignores it and uses the current default.

Example

* list

00010 DIM X$[10]

  LET X$="$H EXAMPLE"

  REM $H X$

  REM $H X$ 10

  REM $H X$

  REM $H X$ 7

  REM $H X$ 8

* run

000001 24 48 20 45 58 41 4d 50 4c 45 $H

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 044 110 040 105 130 101 115 120 $H EXAMP

000009 114 105 LE

See also

$DISPLAY


$HEX

$HEX ------------ Display the contents of the specified string variable

Type

U/BL command.

Syntax

$HEX var$ [base]

Arguments

var$ | A string variable
base | The base in which the contents of the string are to be displayed.

Description

The $HEX command displays the contents of string variable specified. The default base is 16 (hexadecimal). The second parameter can be used to specify a new base. This new base will then become the default for subsequent $HEX commands. If an invalid base, for example, 7 is used, the $HEX command will ignore it and use the current default.

This command is an alias for the $H command.

Example

* list

00010 DIM X$[10]

  LET X$="$HEX EXAMPLE"

  REM $HEX X$

  REM $HEX X$ 10

  REM $HEX X$

  REM $HEX X$ 7

  REM $HEX X$ 8

* run

000001 24 48 20 45 58 41 4d 50 4c 45 $H

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 036 072 032 069 088 065 077 080 076 069 $H EXAMPLE

000001 044 110 040 105 130 101 115 120 $H EXAMP

000009 114 105 LE

See also

$DISPLAY

$H


HELP

HELP ---------- Allows a program to invoke the Help facility

Type

U/BL command and statement

Syntax

HELP(major$,minor$)

Arguments

major$ | A string expression specifying the main Help topic.
minor$ | A string expression specifying the minor Help topic.

Description

The HELP statement allows a program to invoke the Help facility. The major$ parameter is a string expression identifying the major help topic, that is, the "program" in a "." line, and the minor$ parameter is a string expression identifying the minor help topic, that is, the item name in a "!" line. Both of these may be NULL or omitted, in which case the current program name is used for major$, and the menu of items will be shown.

Examples

HELP

HELP("","General")

HELP(X$,Y$)


HOT

HOT ---------- Define a hot key to a subroutine within the current program

Type

U/BL command and statement

Syntax

HOT(n,line[,oldline])

Arguments

n | A numeric variable specifying hot key number, 1 to 10
line | A numeric variable specifying a valid subroutine line number
oldline | The previous subroutine line number

Description

The HOT statement allows the user to define a hot key to a subroutine within the current program.

The oldline parameter is optional and retains the original 'line'. After use the hot key action will again revert to be actioned by 'line'. The ten hot keys are specified as having values of 201-210 decimal, and can be mapped to any key (or combination) via the terminal definition file (TDF).

Note: It is not possible to hot key directly to a line number in a shared memory subroutine.

Example

In an Order Entry program:

01000 HOT(1,5000)

:

02000 GETCUST(1000,........) : A SHARED MEMORY SUBROUTINE

:

05000 REM Pop up window with Product Enquiry

05010 _PRODENQ (..............)

The shared memory subroutine, GETCUST, could also contain the use of Hot Key 1:

01000 REM Shared Subroutine GETCUST

01500 HOT(1,9000,OLDLINE)

:

: shared subroutine code

:

09000 HOT(1,OLDLINE)

09999 RETURN

Line '09000 HOT(1,OLDLINE)' will reset the Hot Key back to the original line used in the calling program, that is, line 5000, just before returning to the calling program.


HOTSPOT

HOTSPOT ---------- Declares an area of the screen that responds to mouse clicks

Type

Windows Object Command

Syntax

HOTSPOT ( ROW, COL, HEIGHT, WIDTH, RETMODE, RETURNTEXT$, DISPLAYMODE, DISPLAYTEXT$ [, STAT] )

Arguments

ROW | The location of the top of the hotspot
COL | The location of the left hand side of the hotspot
HEIGHT | The number of rows in the hotspot
WIDTH | The number of columns in the hotspot
RETMODE | Describes how the hotspot will return data
RETURNTEXT$ | The text to be returned if cursor mode is not selected
DISPLAYMODE | Describes how the hotspot will appear
DISPLAYTEXT$ | Specifies any text to be displayed within the hotspot
STAT | Optional status return.

Description

The HOTSPOT command declares a region of the current window to be mouse-sensitive. This hotspot occupies the area containing NROWs below ROW, which is NCOLs wide starting at column COL. The appearance of this region is determined by the DISPLAYMODE parameter which can be set to the following values:

Value | Description
3 | Displays the hotspot as a Windows 3D-look button
2 | Display the hotspot as an area colored in current hotspot color. This defaults to red but can be changed by a: SETGUIOP(3, COLOUR$)
4 | The hotspot is invisible (nothing is displayed)

Unless the hotspot has been defined to be invisible, any text specified in the DISPLAYTEXT$ parameter is displayed in the hotspot. This text will normally appear center justified but it can also be right or left justified by using the SETGUIOPT function 4.

The hotspot is active once it has been defined and will place its return into the keyboard buffer as soon as the user clicks over the hotspot. Exactly what is returned to the program depends on the RETMODE parameter:

Value | Description
0 | When clicked, the hotspot returns the string @@<x>;<y>;Where <x> is the horizontal character coordinate and <y> the vertical coordinate of the mouse pointer relative to the current window.
1 | When clicked, the hotspot returns the text in RETURNTEXT$

Note: Hotspots are not Windows objects. The Windows object modifiers like SETTEXT, or the SETGUIOPT function to select fractional sizing (SETGUIOPT(14, SCALE$)) will not work against hotspots.

See Also

CLEARHOTSPOTS

Error codes

SETGUIOPT


@INPUT

@INPUT ---------- Accepts screen formatted input from user

Type

U/BL statement.

Syntax

@INPUT(fld,num,rec$[,sfld])

Arguments

fld | A numeric expression for the first field in a set of fields to be input.
num | A numeric expression for the number of fields to input.
rec$ | A string variable which will receive the fields as they are @INPUT. rec$ can be set up to hold the fields' default values.
sfld | An optional numeric expression for the field number at which the @INPUT is to start. The default value is 1 and the @INPUT will start at the field specified by the fld parameter. If sfld is zero, then the @INPUT will start at the last of the specified fields.

Description

The @INPUT statement supports hot-keys to another Basic program, a subroutine in the current program or to an operating system command. The current field and input data are restored on return to the @INPUT. The following limitations apply:

  • Hot-keys do not work on "option" fields within an @INPUT statement.

  • Any @INPUT which is called in the hot-keyed code (program or subroutine) will not work correctly, and will cause the original @INPUT to re-start on return from the hot-key (rather than preserving the #FIELD number and INPUT data).

If the environment variable BBATINPWAIT is set to Y, and if an unpend table is in use, then U/BL will wait for any characters which may follow an ESC used in the unpend table.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

:

00140 @BLANK(1,1,CAT$)

00150 @BLANK(1,1)

00160 @INPUT(1,1,CAT$)

:

See also

BBATINPWAIT

@BLANK

@DESC

@PRINT


$I

$I --------- Disable the ON IKEY statement

Type

U/BL command.

Syntax

$I

Description

The $I command disables the ON IKEY statement. This is a toggle on/off, and it ignores the STMA 6,5 setting. An IKEY is always generated when $I is set, regardless of whether or not IKEY has been switched off by STMA 6,5.

See also

INTERRUPT


$IREPLACE

$IREPLACE ---------- REPLACEs a program while deallocating strings and arrays

Type

U/BL statement and command

Syntax

$IREPLACE [program$]

Arguments

program$

A string expression containing the name under which you want to save the program.

Description

The $IREPLACE command saves the program in memory but it doesn't retain the contents of its variables, the GOSUB stack, or the position reached for a CON statement to resume from.

If a file with the specified name already exists, it is overwritten.

If the program$ parameter is not specified, the current program name is used. This name is set by the last LOAD, RUN, SAVE or REPLACE statements and defaults to SCRATCH. If a pathname is not specified within the program$ parameter, the program is saved in the current directory. The current program name does not include a pathname.

Use the $IREPLACE command to save memory and speed up SAVEs. This is a useful statement when it is not important to keep the old variable values, which can occupy a lot of space, but are not needed for future execution.

Example

The following short program would require a lot of (useless) disk space if RUN and then REPLACEd:

* list

00010 DIM A$[500000]

00020 LET A$=FILL$(32)

However, the wastage can be avoided by:

* $ireplace "test

See also

$ISAVE

BBSAVE

REPLACE

REPLACEV

SAVE

SAVEV


$ISAVE

$ISAVE ---------- SAVEs a program while deallocating strings and arrays

Type

U/BL statement and command

Syntax

$ISAVE [program$]

Arguments

program$

A string expression containing the name under which you want to save the program

Description

The $ISAVE command writes the program in memory but it doesn't retain the contents of its variables, the GOSUB stack or the position reached for a CON statement to resume from.

If the environment variable BBEXTN is set, then the specified ".extension" will be appended to the program$ parameter.

If the environment variable BBPROGS is set, the program will always be saved in the first directory specified unless a pathname is used.

If a file with the specified name already exists, the following error message is displayed:

I/O error 9 - File already exists

This error can be trapped with an ON ERR statement. If the program$ parameter is not specified, the current program name is used. This name is set by the last LOAD, RUN "program", SAVE or REPLACE statement and reset by a NEW statement. It defaults to SCRATCH.

If no pathname is specified within the program$ parameter, the program is saved in the current directory. The current program name does not include a pathname.

Use this command to save memory and speed up SAVEs. This is a useful statement when it is not important to keep the old variable values, which can occupy a lot of space, but are not needed for future execution.

Example

The following short program would require a lot of (useless) disk space if RUN and then SAVEd:

* list

00010 DIM A$[500000]

00020 LET A$=FILL$(32)

However, the wastage can be avoided by:

* $isave "test

See also

$IREPLACE

BBSAVE

REPLACE

REPLACEV

SAVE

SAVEV


IASC

IASC ---------- Extracts a signed number from a string

Type

U/BL function.

Syntax

IASC(string$)

Arguments

string$

A string from which the number is to be extracted

Description

The IASC function extracts a signed numeric value from a string. In most cases, it is the inverse of the CHR$ function. When used for extractions from strings of 4 bytes (6 bytes under triple precision Business BASIC), it is identical in behavior to the ASC function.

When working with strings less than 4 bytes (or 6 bytes under triple precision), IASC works differently: it automatically assumes that the high-order bit of the leftmost byte is a sign bit, and corrects the result accordingly. This sign correction is similar to the formula for the ASC function

If the CHR$ function was used to store a positive number in fewer than 4 bytes (6 bytes under triple precision), and the number is large enough to use the sign bit, the result is a complemented negative number. For example, if 255 is stored in 1 byte using the CHR$ function, for example, X$=CHR$(255, 1), IASC of the string would be -1. To prevent the storage of signed numbers that exceed the number of destination bytes, use ICHR$.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

DIM X$(1)

  INPUT X

  X$=CHR$ (X, 1)

  X=ASC (X$)

  X=OR (X, -AND (X, 2^7))000000

  PRINT "RESULTS: " ,IASC (X$) ,ASC (X$) ,X

  GOTO 10

When executed, this program produces the output displayed below:

? 1

RESULTS: 1 1 1

? -10

RESULTS: -10 246 -10

? 130

RESULTS: -126 130 -126

? 257

RESULTS: 1 1 1

!! STOP AT 0010


ICHR$

ICHR$ ---------- Stores a signed number in a string

Type

U/BL statement or command.

Syntax

ICHR$(number,bytes)

Arguments

number | A signed numeric expression to be stored in the string
bytes | The number of bytes in which to store the number.

Description

The ICHR$ function stores a signed numeric value in a string. This is the inverse of the ASC function in most instances, and identical in behavior to the CHR$ function when used for storage in strings of 4 bytes (6 bytes under triple precision Business BASIC). ICHR$ differs from CHR$ when working with strings less than 4 bytes (6 bytes under triple precision). ICHR$ automatically allocates the highest-order bit of the destination byte(s), the storage occurs, along with the sign bit. If the number to the stored "overflows" the destination byte(s), a BASIC run-time error (#99) occurs. This error checking occurs in ICHR$, but not in CHR$.

The largest positive number that can be stored in n bytes with ICHR$ is (2^K)-1, and the largest negative number is -(2^k), where k=(n*8)-1, as shown in the following example:

For storage in | Maximum | Minimum
1 byte | 127 | -128
2 bytes | 32767 | -32768
3 bytes | 8388607 | -8388608
4 bytes | 2147483647 | -2147483648
5 bytes (triple precision) | 8796093022207 | -8796093022208

ICHR$ does not change the way any subsequent extraction behaves. If fewer than 4 bytes (6 bytes in triple precision) are used to store a signed numeric value, and ASC is subsequently used to extract the value from the same byte locations, the sign for that value must be corrected or it appears as a complemented positive number. See the ASC function for more detailed information. If IASC is used to retrieve the signed numeric value, the sign is automatically corrected. See the IASC function for more detailed information.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

  ON ERR THEN GOTO 100

  DIM X$ (100)

10 INPUT X

20 X$=ICHR$ (X, 1)

30 X=ASC (X$)

  X=OR (X, -AND (X, 2^7))

  PRINT "RESULTS:" ,IASC (X$) ,ASC (X$) ,X

  GOTO 10

100 :Error handler

  X$=TRUN$ (ERM$ (SYS(7)), 1)

  PRINT "Error at" ;SYS(20) ;".Number" ;SYS(7) ;":" ;X$

  IF SYS(20)=20 THEN GOTO 10

  END

When executed the program produces the output displayed below:

? 1

RESULTS: 1 1 1

? -10

RESULTS: -10 246 -10

? 130

Error at 20. Number 99 :Number too large for destination byte(s)

? -257

Error at 20. Number 99 :Number too large for destination byte(s)

!! STOP AT 0010


IF... THEN... ELSE...

IF... THEN... ELSE... Allow conditional execution or branching

Type

U/BL statement

Syntax

Format 1:

IF expr [THEN] st_or_ln [ELSE st_or_ln]

Format 2:

IF expr [THEN]

   block of statements

[ELSE

   block of statements]

END IF

Arguments

expr | Any expression resulting in a value of true or false, or in numeric value where 0 is taken as false and any other value as true.
st_or_ln | Either any valid U/BL statement, or a valid line number or label in the current program.
statement | Any valid block of U/BL statements

Description

The IF statement allows different statements to be executed, or for the program to transfer control, depending on a condition. If the condition is TRUE, the THEN part of the IF statement is executed, and the ELSE part (if any) is not. If the condition is not TRUE, then the ELSE part of the IF statement is executed if it is present, or no statement within the IF, if there is no ELSE part.

Unless the IF contains a GOTO statement, program execution continues from the next executable statement after the IF statement or block.

The single line IF statement is best suited for short, straightforward tests where only one action is taken. The block form offers several advantages: structured code, multiple statements for both THEN and ELSE parts of the IF and nested IF statements to any level.

Each ELSE statement matches up with the last unmatched IF. Normally, block IF statements are formatted so that indentation shows which ELSE matches up with which IF statement. If necessary, THEN and GOTO keywords are inserted when reformatting.

Example

* list

00005 DIM X$[10],Y$[10]

00010 LET A=1 \ B=2 \ X$="hello" \ Y$="goodbye"

00020 IF A<B THEN PRINT "less"

00040 IF A<B THEN PRINT "still less" ELSE PRINT "greater"

00210 IF X$<>Y$ THEN

00220 IF X$>Y$ THEN

00230 PRINT "greater"

00240 ELSE

00250 PRINT "less"

00260 END IF

00270 ELSE

00280 PRINT "equal"

00290 END IF

* run

less

still less

greater


INCLUDE

INCLUDE ---------- Includes another file in the current source file during a compile

Type

U/BL statement.

Syntax

INCLUDE filespec

Arguments

filespec

The filespec containing the code to be included

Description

The INCLUDE statement allows you to include another Business Basic source file into the current source file during a compile. You can include up to three nested levels in the current source file. If the nested level of files included in the current source file exceeds three, a compile error (#95) is returned.

You must not allow the line numbers of the file to be included to overlap. In the example below, all of the line numbers in HELLO.LS must be between 10 and 30.

Example

10 PRINT "TEST OF INCLUDE STMT"

  INCLUDE AFILE.S

30 PRINT "TEST COMPLETE"


INDEXEXTEND

INDEXEXTEND ---------- Converts a standard or ISAM+ index file to an Extended Index

Type

U/BL statement.

Syntax

Syntax 1 | INDEXEXTEND(file_type(=0),sub_file_no,extent_size,extend_from,stat)
Syntax 2 | INDEXEXTEND(file_type(=1),channel,offset,extent_size,extend_from,stat)

Arguments

file_type | 0 = a logical file; 1 = another type of file.
sub_file_no | For logical files. The file number that was used in the LOPEN statement.
channel | For other file types. The channel that the file was OPENed on.
off_set | The index file's offset within the physical file.
extent_size | The size of each extent expressed in blocks. A extent_size of -1 selects the default size of 100 blocks.
extend_from | Specifies the location, within the physical file, before which extents will not be created. Specifying an extend_from of -1 defaults this position to be current size of the file.
stat | Return status (0 - all OK, not 0 - error).

Description

The INDEXEXTEND statement flags a standard or ISAM+ index file as an extended index. This allows the index to automatically increase its storage allocation whenever its initial space has been exhausted. When full, an extended index will grab an additional area of disk space from the end of the physical file. This area, or extent, is then employed as an integral part of the index.

An extended index can use up to a maximum of 64 extents, the size of which being specified (in blocks) by the extent_size parameter in the INDEXEXTEND command. Extending an index thus provides an additional 64 * extent_size index blocks.

Note: With "normal" two byte pointers and 512 byte index blocks, the maximum size of an index (including extents) is 65 534 * 512 = 32 Mb. For 2 048 byte block indexes, the maximum is 65 534 * 2 048 = 128 Mb.

An extended index cannot use more blocks than this maximum, that is, Initial-index-size + 64 * extent_size must be less than 65 534 * block_size. With the three byte pointers and 2 048 byte blocks of an ISAM+ index, the limit for each index file is theoretically 16 777 215 * 2 048. However, due to the maximum size of a file being limited by the operating system (to 2 147 483 647 bytes), the effective maximum is 1 048 575 * 2 048 bytes or 2Gb.

Whenever an index extension is created (if KADDing a key exhausts the index's currently allocated disk space) it is assembled at the end of the physical file. For this reason, it is imperative that this location is past the end of the last logical file that is in the physical file. If this not the case, the extent will be created in a location that will eventually be used by the last logical file.

In order to ensure that this form of corruption cannot occur, the INDEXEXTEND statement provides a parameter, extend_from, which specifies the earliest location in the file where an extent can be created. If this parameter is specified, the physical file is automatically padded to this length in order that any extents are created past this point. This is particularly useful if the other logical files have not been null-filled o the user wishes to reserve some space in which to create some new logical files.

There are two possible locations to allow the extents to be created:

  1. At the end of the logical data file:

This allows the data file to extend as normal, protecting the extent from being over-written when this happens. Selecting this approach does not preclude adding a new logical file at a later date, as long as this new file is added to the end of the physical file (rather than directly after the calculated end of the last logical file). In addition, the new logical file must be padded out to its full length (either null filled, or a byte written out at the location of the end of the logical file).

  2. After allowing some spare space following the logical data file:

This allows the data file to extend without effecting the extent and also provides some spare disk space that can be used for a new logical file at a later date.


INIT FILE

INIT FILE ---------- Initializes or purges the contents of a disk file

Type

U/BL statement.

Syntax

INIT FILE(channel),lastrec,delrec[,nactrec]

Arguments

channel | A numeric expression containing the channel number on which a file is open in the exclusive mode
lastrec | A numeric expression containing the record number to which the field of the highest record number is to be set
delrec | A numeric expression containing the record number to which the field of the first deleted record number is to be set
nactrec | A numeric expression defining the number of active records in the file (optional)

Description

The INIT FILE statement initializes or purges the contents of a disk file, of the following types:

  • type D (data)

  • type I

  • type J (index)

  • type T (text)

All files must be open in an exclusive mode. INIT FILE provides control of dynamic record allocation in linked-available files, and of the #-of-bytes-of-text field in the File Control Block of a type T file.

The values that you indicate in INIT FILE set the highest-record-number-used and first-deleted-record-number fields in the file's File Control Block. If the file is an index file, these values must be zero. The values are also normally zero for a data file except when the deleted record chain is being reconstructed, or when a file is being duplicated or copied. The #-of-bytes-of-text field is set automatically to zero.

If the file is not opened in the exclusive mode when the INIT is executed, a run time error (# -166) occurs.

Example

This program is used to initialize a SuperDOS linked-available file. This sets the "first-record-deleted" and "last-record-used" fields to the normal initialized values of 0 & 0.

10 DIM FN$ (17)

20 INPUT USING " " ,"ENTER A FILE NAME " ,FN$

30 OPEN FILE (0, 6) ,FN$ :OPEN EXCLUSIVELY

40 INIT FILE (0) ,0 ,0 :INITIALIZE FILE

50 CLOSE

60 END


INPUT

INPUT ---------- Accepts input from the keyboard

Type

U/BL command and statement

Syntax

INPUT [control] [prompt,] var [,[control] [prompt,] var]...[;]

Arguments

control | Any @() expressions to position the cursor, control the terminal and/or restrict input.
prompt | A quoted string literal printed as a prompt before terminal input is accepted. If no prompt is specified a question mark is the default.
var | A numeric or dimensioned string variable to receive the value of the input.

Description

The INPUT command causes the program to pause and print a prompt indicating it is waiting for data. The user can then type the data at the keyboard. A terminating semi-colon leaves the cursor on the same line as the INPUT statement. If more than one variable is included in the INPUT statement, the initial prompt is displayed and the program waits for data. The user can type one item, or several. User input is normally finished by an unpend key being pressed.

Unpend keys can be set by using the STMA 4 statement, by the terminal control argument, or in the terminal definition file (tdf), but they usually default to carriage return and line feed characters. If the terminal control argument (-10,-x) is used, where x is the maximum length of input, input terminates automatically when x characters have been typed. If fewer items are typed than there are variables provided, the program stores them in the appropriate variables, and prompts for the next.

The commas in an INPUT USING statement are interpreted as delimiters. Any leading blanks are ignored unless the input is a string enclosed in quotes. A string enclosed in quotes may also contain embedded commas without them being interpreted as delimiters. The quotes themselves are stripped from the string.

Any number enclosed in angle brackets (<>) in a string being input is converted to the ASCII character corresponding to the number. INPUT of a string to a numeric variable causes the bell to ring and the variable is prompted for again with a "\? ?" prompt.

Examples

1. Using the default prompt

* input x

? 1

* input x,y,z

? 1 ? 2,3

2. Using defined prompt

* dim x$[60]

* input "Enter a number...",a," and a string...",x$

Enter a number...1 and a string... ? Transoft Ltd.

3. Restricting length of user input

* dim x$[60]

* input @(-10,3),"Enter up to three characters...",x$

Enter up to three characters...abc

4. Input a string containing a comma

* input x$

? Curses, like chickens, come home to roost

* print x$

Curses

* input x$

? "Little thieves are hanged, but great ones escape"

* print x$

Little thieves are hanged, but great ones escape

5. Show error handling

* input "Enter a number...",a

Enter a number...Transoft\? ? 3

See also

INPUT USING


INPUT FILE USING

INPUT FILE USING ---------- Reads data items from a file with error and delimiter trapping

Type

U/BL command and statement

Syntax

INPUT FILE[channel], USING "",variable{,variable}...

INPUT FILE[channel], USING "",string${,delim$}

Arguments

channel | A numeric expression representing the channel number used to open the file.
variable | A numeric variable or numeric array to receive the value or values of the input.
string$ | A string variable which receives the input.
delim$ | A string variable which receives the value of the delimiter.

Description

The INPUT FILE USING statement works in a similar way to the INPUT FILE statement. Any error can be trapped with an ON ERR statement, and the delimiter between data items can be captured.

Any number of numeric values can be read from the file using this statement, or one string value, but numeric and string values cannot be mixed. If the second format is used, and the delimiter$ variable is included, the delimiting character is placed in the delimiter$ variable.

The INPUT FILE [16], USING statement behaves in the same way as the INPUT USING statement.

Example

* list

00010 DIM X$[80],DELIM$[1]

00020 OPEN FILE[0,0],"TESTFILE"

00030 PRINT FILE[0],"Transoft Ltd"

00040 POSITION FILE[0,0]

00050 INPUT FILE[0],USING "",X$,DELIM$

00060 PRINT X$;" ";ASC(DELIM$)

00070 CLOSE FILE[0]

* run

Transoft Ltd 10

See also

INPUT

INPUT USING


INPUT FILE

INPUT FILE ---------- Reads data items from a file

Type

U/BL command and statement

Syntax

INPUT FILE[channel], variable {,variable}... {;}

Arguments

channel | A numeric expression representing the channel number of an open file.
variable | A numeric or string variable to receive the value of the input.

Description

The INPUT FILE statement performs the same function as INPUT command, but reads its data from a file rather than from the keyboard. The data read by one INPUT FILE statement must be separated from other data by null, form feed, carriage return or new line characters. If several variables are read by one INPUT FILE statement, they must be separated by commas in the file. Data written to file with PRINT statements, is suitable for reading with INPUT statements.

The INPUT FILE[16] statement behaves exactly like the INPUT command, using the same terminal control and prompt arguments.

Using the INPUT FILE statement to input a string to a numeric variable, results in the error 46 -"Invalid input".

Example

* list

00010 DIM X$[80]

00020 OPEN FILE[0,0],"TESTFILE"

00030 PRINT FILE[0],1;",";"2";",";"Transoft Ltd"

00040 POSITION FILE[0,0]

00050 INPUT FILE[0],A,B,X$

00060 PRINT A;" ";B;" ";X$

00070 CLOSE FILE[0]

* run

1 2 Transoft Ltd

See also

INPUT

INPUT FILE USING


INPUT USING

INPUT USING ---------- Accepts input from the keyboard with error and delimiter trapping

Type

U/BL command and statement

Syntax

INPUT USING "", [prompt,] var [,var]...

INPUT USING "", [prompt,] string$ [,delim$]

Arguments

prompt | A quoted string literal printed as a prompt before terminal input is accepted. If no prompt is specified a question mark is the default. Cursor positioning, terminal control and/or input restrictions can be specified here with @() codes.
var | A numeric variable or numeric array to receive the value or values of the input.
string$ | A string variable which receives the input.
delim$ | A string variable which receives the value of the delimiter.

Description

The INPUT USING statement works in a similar way to the INPUT statement, but the following differences exist:

  • Errors can be trapped with an ON ERR statement

  • The unpend key can be trapped

  • All values must be input at once.

Any number of numeric values can be input from the keyboard using this statement, or one string value, but numeric and string values cannot be mixed.

If the second format is used, the delimiting character is placed in the delim$ variable. A string being input can contain commas without needing to be enclosed in quotes, and any leading spaces are retained. Quote marks are not stripped.

Examples

1. Accepting an integer with an error trap.

01000 REM input an integer

01010 ON ERR THEN GOTO 10025

01015 PRINT

01020 INPUT USING "","Enter any integer...",I

01030 ON ERR THEN INT

* run

Enter any integer...A good horse cannot be of a bad colour

Enter any integer...3

2. Accepting a string with embedded commas.

* list

0005 DIM X$[50]

0010 INPUT USING "","Enter a string...",X$

0020 PRINT X$

* run

Enter a string...Transoft Limited, Slough

Transoft Limited, Slough

See also

INPUT


INQUIRE

INQUIRE ---------- Returns the value of the specified tdf keyword

Type

U/BL statement or command.

Syntax

INQUIRE(subject$,topic$,result$[,er])

Arguments

subject$ | There are two subjects currently supported, tdf and tables
topic$ | If the subject is tdf, then this argument can be any tdf keyword (with the exceptions of kbf_ and kbt_). If the subject is tables, then this argument can be jobs, locks or files.
result$ | The format of the information returned in this argument depends on subject and topic being inquired on.
er | A numeric variable which will be set to one of the following: 0 - the INQUIRE command was successful 1 - an unknown subject was used 2 - an unknown topic was used 3 - result$ was not DIMensioned large enough 4 - not enough internal memory available

Description

If the subject is tdf, then the INQUIRE command returns the value of the specified tdf keyword. The first byte of the result$ argument holds the keyword's length. If the keyword is not in the TDF, then the result$ argument returns a zero length string.

Note: The INQUIRE command cannot return the values of kbf_ and kbt_ keywords.

If the subject is tables and the topic is jobs, the format of the result$ argument is:

Bytes | Contents | PACK format
01-02 | Maximum number of jobs | J
03-04 | Number of active jobs | J

For each active job, a repeating number of the following packet will be stored in the result$ argument from byte 5 onwards:

Bytes | Contents | PACK format
05-08 | UNIX pid | L
09-10 | Job type | J
11-26 | Login name | S16
27-42 | Current program name | S16
43-52 | Device name | S10
53-54 | SYS(4) value | J
55-56 | SYS(9) value | J
57-58 | Current line number (if BBSTMT=Y) | J
59-68 | BBUSER value | S10
69-78 | BBMACHINE value | S10
79-82 | Status (UNIX only) 1=waiting on input 2=blocked on a lock | L
83-98 | Filler (nulls) | A16

If the subject is tables and the topic is locks, the format of the result$ parameter is:

Bytes | Contents | PACK format
01-02 | Maximum number of locks | J
03-04 | Number of active locks | J

For each active lock, a repeating number of the following packet will be stored in the result$ parameter from byte 5 onwards:

Bytes | Contents | PACK format
05-08 | UNIX pid | L
09-12 | LOCK id | L
13-16 | Start byte | L
17-20 | Stop byte | L
21-22 | SYS(9) value | J
23-32 | File name | S10
33-35 | Lock start - high bytes (LFS) | L
36-39 | Lock stop - high bytes (LFS) | L

Bytes 33 to 39 of this packet are only included if Large File Support is enabled. This allows for start and stop positions greater than 4GB.

If the subject is tables and the topic is files, the format of the result$ argument is:

Bytes | Contents | PACK format
01-02 | Maximum number of files | J
03-04 | Number of open files | J

For each open file, a repeating number of the following packet is stored in the result$ argument from byte 5 onwards:

Bytes | Contents | PACK format
05-08 | inode value | L
09-12 | Dev | L
13-14 | Exclusively open (1=exclusive, 0=shared) | J
15-34 | File name | S20
35-36 | Number of users using file | J
37-38 | SYS(9) value (repeated for every user using the file). | J

Example

00100 INQUIRE("tables","jobs",X$)

00110 UNPACK "JJ",X$,MAX_JOBS,ACT_JOBS

00120 UNPACK "LJS16S16S10JJJS10S10L",X$[5],PID,TYPE,NAME$,PRG$,DEV$,SYS4,SYS9 LINE,BBUSER$,BBMACHINE$,STATUS


INSTALL

INSTALL ----------- Installs the current program in the shared library and ENDs

Type

U/BL command and statement

Syntax

INSTALL(status)

Arguments

status

A numeric variable which will be set to zero if the INSTALL was successful, or non-zero if it wasn't.

Description

The INSTALL statement installs the current program in the shared library and ENDs. This will enable installation of the library by SWAPing to all the modules that are needed by a startup program. Each module would be headed by a list of ENTRY statements followed by an INSTALL statement.

Example

00010 SHARE("TEST")

00020 ENTRY("PRINTIT",1000,A$,N)

00030 INSTALL(STAT)

00040 IF STAT<>0 PRINT "Install Error ";STAT

00050 END

01000 REM

01010 FOR I=1 TO N

01020 PRINT A$

01030 NEXT I

01040 A$=FILL$(66)

01050 N=N*2

01060 RETURN

09999 END

Once INSTALLed this would be called from a Basic program as:

00200 PRINTIT(MSG$,20)

See also

ENTRY

SHARE

Shared Memory Procedures


INT

INT ---------- Returns the integer part of it's argument

Type

U/BL function

Syntax

INT(expr)

Arguments

expr

A numeric expression

Description

The INT function returns the integer part of the value specified in the expr parameter.

Example

* $NUMERIC A(0.4)

* LET A=123.456

* PRINT INT(A)

123

See also

$NUMERIC


INTERRUPT

INTERRUPT ---------- Turns U/BL's asynchronous interrupts on or off

Type

U/BL command.

Syntax

INTERRUPT(mode)

Arguments

mode

1 - asynchronous interrupts on (default)

0 - asynchronous interrupts off

Description

The INTERRUPT command turns U/BL's asynchronous interrupts on or off. By default, U/BL enables asynchronous interrupts. If an IKEY is pressed, U/BL will perform any IKEY processing before it executes the next statement in a program (this is to ensure the integrity of data files).

Problems can occur however, when the currently defined IKEY generates the same value as other keys. For example, on most UNIX machines the function keys generate ESC (decimal 27) as the leading value for their escape sequences.

To get around this problem the asynchronous interrupts can be disabled by with the INTERRUPT(0) command.

This only allows IKEY processing on INPUT statements. In order to ensure that a program which does not contain any INPUT statements can be interrupted, then CTRL-C automatically becomes the asynchronous IKEY and will interrupt the program as if the primary IKEY has been pressed.

Example

* list

00010 FOR I=1 TO 100

00020 PRINT "hello"

00030 DELAY 10

00040 NEXT I

* _interrupt(1)

* run

hello

hello

hello

hello <Primary IKEY pressed here>

IKEY at 30

* _interrupt(1)

* run

hello

hello

hello

hello

hello <Primary IKEY pressed here - now has no effect>

hello

hello

hello <CTRL-C (now the asynchronous IKEY) pressed here>

IKEY at 30

See also

$I

BBMIKEY

BBSIGNAL

ON IKEY

STMA 3

STMA 4

STMA 5

STMA 6

STMA 7


JOBBYE

JOBBYE ---------- Aborts a task and logs it off the system

Type

U/BL statement.

Syntax

JOBBYE task

Arguments

task

A numeric expression containing the task number of the task to be logged off the system

Description

The JOBBYE statement aborts the specified task and logs it off the system. This is equivalent to a BYE command issued by the task itself.

When this statement is executed, the user level must be 7. If the user level is not 7, a run-time error occurs. A run-time error also occurs if the task number specified is greater than 255. However, if the task number is less than 256, but the task is not configured or active, no error is returned and the statement is essentially ignored.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

1. General example.

This example below demonstrates the use of the JOBBYE statement. It displays the current system tasks, then prompts the user for the task number to log off.

Note: The variable NTASKS is different for each system configuration.

*list

10 DIM X$ (10) \ TASK=0 \ NTASKS=10 :Init

20 PRINT

30 SWAP "MMI TA" :Display tasks

40 PRINT

50 INPUT USING " " ,@ (-25) ,"Task number to log off: ",@ (-10,2) ,X$

60 TASK=VAL (X$, E) :Extract task#

70 IF (TASK<1 ? TASK>NTASKS ? E<>0) THEN :Is it valid?

72 PRINT "Invalid task number" ;TASK

74 DELAY 20 \ GOTO 10

76 END IF

80 #ERRJMP OFF \ JOBBYE TASK \ #ERRJMP ON :BYE task

90 IF #ERR <>0 THEN :Check for errors

92 PRINT "Unable to log off task number" ;TASK

94 END IF

99 END

Notes

  • When a program is stopped with the JOBBYE statement, you can encounter problems. U/BL ends the program without clearing any resources, BASIC locks, and so on. It is better to end a program using the END statement.

  • If you need to stop a background task, it is recommended that the program check for a user-defined flag, then end if it is ON. The controlling program would set and clear this flag to control the background job.

The examples below demonstrate the use of a flag to end a background task. The background program is started by the controlling program and continues running until the controlling program sends a "1" to FLAG. The controlling program is started by the user at a terminal and waits for input from the user to send the "1" to the background program. Note that any available task number can replace the 7 used in the example.

2. Controlling program

10 FORCE 7, BACKGROUND :Start Background program on task 7

20 INPUT USING " ", "ENTER 1 to end Background program: " ,FLAG :Wait for the user to enter 1

30 REPLY 7, "1(13)" :Send 1 (and carriage return), to turn on FLAG in Background program

40 END

3. Background program

10 FLAG=0 :Initialize FLAG to off

  OPEN FILE (1), "$LPT" :Open system printer

20 TINPUT 5, FLAG :Wait 5 for input from controlling program, continue if no input

30 IF FLAG=1 THEN GOTO 50 :Check FLAG, end program if on

40 PRINT FILE (1), "VALUE OF X=" ;X ;continue processing if FLAG is off

  X=X+1

  GOTO 20

50 CLOSE :close files and end the program

  END


JOBCOUNT

JOBCOUNT ---------- Returns the maximum number of foreground and background jobs, available on the system

Type

U/BL command and statement

Syntax

JOBCOUNT(max_fg,act_fg,max_bg,act_bg)

Arguments

max_fg | The maximum number of foreground jobs
act_fg | The number of active foreground jobs
max_bg | The maximum number of background jobs
act_bg | The number of active background jobs

Description

The JOBCOUNT statement returns the maximum number foreground and background jobs, available on the system. It also returns the number of currently active jobs.

Example

* list

00010 JOBCOUNT(MFG,AFG,MBG,ABG)

00020 PRINT "There are currently ";AFG;" Active Foreground jobs and"

00030 PRINT ABG;" Active Background jobs (Maximum number of jobs is ";

00040 PRINT MFG+MBG;")"

* run

There are currently 2 Active Foreground jobs and 0 Active Background jobs (Maximum number of jobs is 40 )


JOBIKEY

JOBIKEY ---------- To interrupt a task

Type

U/BL statement.

Syntax

JOBIKEY task

Arguments

task

A numeric expression containing the task number of the task to be interrupted

Description

The JOBIKEY statement interrupts the specified task number. This is different from an operator pressing an interrupt key. When using the JOBIKEY statement, the program just ends.

When you execute this statement:

  • The user level must be 7.

  • The specified task number must be less than 256

If the user level is not 7, a run-time error (#81) occurs. If the specified task number is 256 or higher, a run-time error (#80) occurs. However, if the task number specifies a task that is not configured or active, no error is returned and the statement is basically ignored.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This example demonstrates the use of the JOBIKEY statement. It displays the current system tasks, then prompts the user for the task number to interrupt.

Note: The variable NTASKS is different for each system configuration.

* list

10 DIM X$ (10) \ TASK=0 \ NTASKS=10 :Init

20 PRINT

30 SWAP "MMI TA" :Displays tasks

40 PRINT

50 INPUT USING " " ,@(-25) ,"Task number to interrupt: " ,@(-10, 2) ,X$

60 TASK=VAL (X$, E) :Extract task#

70 IF (TASK<1 ? TASK>NTASKS ? E<>0) THEN :Is it valid?

72 PRINT "Invalid task number" ;TASK

74 DELAY 20 \ GOTO 10

76 END IF

80 #ERRJMP OFF \ JOBIKEY TASK \ #ERRJMP ON :IKEY task

90 IF #ERR <>0 THEN :Check for errors

92 PRINT "Unable to interrupt task number" ;TASK

94 END IF

99 END


JOBINT

JOBINT ---------- To IKEY a task

Type

U/BL statement.

Syntax

JOBINT task

Arguments

task

A numeric expression containing the task number (relative to 1) of the task to be IKEYed.

Description

The JOBINT statement performs IKEY on a task exactly as if the user had pressed the IKEY character. It invokes the ON IKEY logic for the program running in the specified task.

The JOBINT statement differs from the JOBIKEY statement, in that the latter actually aborts the specified task. It is better to use the JOBINT statement instead of the JOBIKEY statement in most cases, but if a task is caught in a loop with the IKEY disabled, you need to use the JOBIKEY statement to halt the program.

If a task is waiting for input when the JOBINT statement is processed, the input is cancelled, unless the IKEY has been set to zero. When the statement is executed:

  • The user level must be 7 when this statement is executed.

  • The specified task number must be less than 256

If the user level is not 7, a run-time error (#81) occurs. If the specified task number is 256 or higher, a runtime error (#80) occurs. However, if the task number specifies a task that is not configured or active, no error is returned and the statement is essentially ignored.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This example demonstrates the use of the JOBINT statement. It displays the current system tasks, then prompts the user for the task number to interrupt.

Note: The variable NTASKS is different for each system configuration.

*list

10 DIM X$ (10) \ TASK=0 \ NTASKS=10 :Init

20 PRINT

30 SWAP "MMI TA" :Displays tasks

40 PRINT

50 INPUT USING " " ,@(-25) ,"Task number to interrupt: " ,@(-10, 2) ,X$

60 TASK=VAL (X$, E) :Extract task#

70 IF (TASK<1 ? TASK>NTASKS ? E<>0) THEN :Is it valid?

72 PRINT "Invalid task number" ;TASK

74 DELAY 20 \ GOTO 10

76 END IF

80 #ERRJMP OFF \ JOBINT TASK \ #ERRJMP ON :IKEY task

90 IF #ERR <>0 THEN :Check for errors

92 PRINT "Unable to interrupt task number" ;TASK

94 END IF

99 END


$KPREV

This is an alias for KPREV. See KPREV.


KADD

KADD ---------- Add a key to an index

Type

U/BL statement and command

Syntax

Format 1: | KADD file_id,buffer$,key$,recnum
Format 2: | KADD desc$,buffer$,key$,recnum

Arguments

desc$ | A string variable containing details of the index file. It must be at least 18 bytes long.
file_id | The logical file number used to LOPEN the index file, or if the environment variable BBEXTENSION is set to SDOS or the environment variable BBKCHAN=Y, the channel number on which the file is OPEN.
buffer$ | A string variable with a length of at least 544 bytes
key$ | tring variable the length of the index key, and containing the key to be added.
recnum | A numeric variable which contains the record pointer, and which is set to zero if the key cannot be added.

Description

The KADD command adds the key$ and recnum specified to the index file, using the buffer$ supplied. The KADD command only writes an index entry. It does not write any data to the data file.

If the key can not be added, the record number is set to zero. The usual reason why a key can not be added is because the index is defined as not allowing duplicates, and the key already exists. If duplicate keys are allowed, the key will be added even if the same key and recnum combination already are in the index.

Note: For 2048 byte indexes a limit of 65536 duplicates of the same key value is imposed.

The index file must have been created as an index, and be open at the time the KADD command is used. Use the logical file number when adding to an index file that is part of a logical file structure. For non-logical files, if running with BBEXTENSION=SDOS or BBKCHAN=Y (and if the index is not a sub file) the channel on which the file is OPEN may be supplied as file_id. If the file is a sub file, (or BBKCHAN is not set to Y) the desc$ descriptor string must be used. This string must contain the following information:

Bytes | Meaning
1-2 | Physical channel number of the open file
3-6 | Byte offset to block 0 of the index if the index is a subfile, or 0 if it is not a subfile.
7-8 | A flag containing 0 if the file is to be locked during keyed access or 1 if it is not to be locked.
9-18 | The logical filename, padded with null characters. This is only required if the file is to be locked.

The variable used as a buffer$ when adding keys should not also be used for other indexes as other keyed statements rely on its contents.

It is advisable to write data records before adding keys in a multi-user system. This avoids the problem of another user trying to read the data record to which the key points before that data record has been written.

Examples

1. Adding records to a logical file structure. The index file has been LOPENed as logical file 1, and a linked-available record file as logical file 2.

00075 REM Get next free record in data file

00080 GETREC 2,RECNO

00081 REM If there are no free records

00082 IF RECNO=-1 THEN

00085 PRINT "No space left in data file"

00090 STOP

00095 END IF

00097 REM Save records position in case kadd fails

00100 LET RECNO2=RECNO

00103 REM Write the data record

00105 LWRITE FILE[2,RECNO],RECORD$

00107 REM Add entry to the index

00110 KADD 1,BUF$,KEY$,RECNO

00113 REM If unable to add entry to index

00115 IF RECNO=0 THEN

00117 REM Delete it from data file again

00120 DELREC 2,RECNO2

00130 PRINT "Can't add key "

00140 ELSE

00150 PRINT "Record added"

00160 END IF

2. This next example is a similar program to example 1, using a PARAM file structure. The following standard subroutines are used: DELREC.SL (starting line 8600), GETREC.SL (line 8400) and POSFL.SL (line 9610). These subroutines are the PARAM equivalents of DELREC, GETREC and the record_number in LWRITE.

00010 DIM DESC$[18],KEY$[10],REC$[80]

00015 DIM BUF$[544],BLOCK$[512],C1[1,3]

00017 REM Set up for open

00020 LET BLOCK$="MYDATA,10,MYINDX,10",FILL$(0)

00030 BLOCK WRITE BLOCK$

00040 SWAP "OPEN"

00050 BLOCK READ BLOCK$

00060 LET POSY=1

00065 REM Transfer info from open to the c1 array

00070 FOR I=0 TO 1

00080 FOR J=0 TO 3

00090 LET C1[I,J]=ASC(BLOCK$[POSY,POSY+3]) \ POSY=POSY+4

00100 NEXT J

00110 NEXT I

00120 REM Set up DESC$

00130 LET DESC$=CHR$(C1[1,0],2),CHR$(C1[1,1],4),"MYINDX",FILL$(0)

00140 INPUT "Enter record key: ",KEY$

00150 IF KEY$="" THEN GOTO 00350

00160 INPUT "Enter data for key: ",REC$

00165 REM Set up file number of mydata for subroutines

00170 LET F%=0

00175 REM Lock record 0 of data file

00180 LOCK 1,"MYDATA",0,C1[0,3]

00190 GOSUB 8400 : GETREC

00200 UNLOCK 1

00210 IF R1=-1 THEN

00220 PRINT "No space left in data file"

00230 STOP

00240 END IF

00250 GOSUB 9610 : POSFL

00255 REM Copy record's position for use with kadd

00260 LET RECNO=R1

00265 REM Add to data file

00270 WRITE FILE[C%],REC$

00275 REM Add key to index

00280 KADD DESC$,BUF$,KEY$,RECNO

00290 IF RECNO=0 THEN

00300 GOSUB 8600 : DELREC

00310 PRINT "Can't add key"

00320 END IF

00330 INPUT "Enter another key: ",KEY$

00340 GOTO 00150

00350 CLOSE

00999 END

See also

BBKCHAN

KDEL

KFIND

KNEXT

KPREV


KDEL

KDEL ---------- Remove a key from an index file

Type

U/BL statement and command

Syntax

Format 1: | KDEL file_id,buffer$,key$,recnum
Format2: | KDEL desc$,buffer$,key$,recnum

Arguments

desc | A string variable containing details of the index file.
file_id | The logical file number used to LOPEN the index file, or if the environment variable BBEXTENSION is set to SDOS or the environment variable BBKCHAN=Y, the channel number on which the file is OPEN.
buffer$ | A string variable with a length of at least 544 bytes.
key$ | A string variable the length of the index key, and containing the key to be removed.
recnum | A numeric variable which, if the index contains duplicate keys, should contain the record pointer for the record to be deleted. The KDEL command sets the recnum to the value of the record pointer of the deleted record, or to zero if the deletion was not successful.

Description

The KDEL command deletes an entry from an index file and places the record number of the entry in the recnum parameter. It deletes only the index entry; any data files are not altered. If the index file allows duplicates, the KDEL command searches the index file for an entry matching the key$ and with a record number the same as the recnum given. If the index does not allow duplicates, the KDEL command only ensures that the key$ matches.

Refer to the section on the KADD command, for an explanation of when to use file_id and when to use desc$.

In a multi-user system it is advisable to lock a data record before deleting it, to ensure no other user is referring to it. It is also recommended to delete first the index entry and then the data record.

For systems using BB2048=RESIZE buffer$ will automatically be re-sized to 2592 bytes when used against a 2048 byte index, to allow the improved performance associated with this feature.

Example

The following subroutine deletes a book record from a data file and its index.

00500 REM Book found

00505 REM Time to wait if record is locked

00510 LOCKCODE=0

00520 LOCK 1,2,RECNO,CODE

00530 IF CODE<>-1 THEN

00540 PRINT "Book is being accessed by someone else"

00550 ELSE

00555 REM Delete the key

00560 KDEL 1,BUF$,BOOK_KEY$,RECNO

00570 DELREC 2,RECNO

00580 UNLOCK 1

00590 END IF

See also

BB2048

BBKCHAN

$KPREV

KADD

KFIND

KNEXT

KPREV


KFIND

KFIND ---------- Retrieve a key from an index file

Type

U/BL statement and command

Syntax

Format 1: | KFIND file_id,buffer$,key$,recnum
Format 2: | KFIND desc$,buffer$,key$,recnum

Arguments

desc$ | A string variable containing details of the index file.
file_id | The logical file number used to LOPEN the index file, or if the environment variable BBEXTENSION is set to SDOS or the environment variable BBKCHAN=Y, the channel number on which the file is OPEN.
buffer$ | A string variable with a length of at least 544 bytes
key$ | A string variable the length of the index key, and containing the key to be found.
recnum | A numeric variable which accepts the record pointer. If the key is not found, but a higher key is, then recnum receives a negative value corresponding to the record pointer of the key which was found. If there is no key greater than or equal to the specified key in the index, recnum is set to zero.

Description

The KFIND command searches an index file for the key$ specified. If the key is found, the associated recnum is returned. If the key is not found, the KFIND command returns the key which would come immediately after the specified key, and its record pointer, but makes the record pointer negative. If the key specified has a higher value than any key in the index, by default the KFIND command returns high values in the key$ field and zero in the recnum field. If, however, the environment variable BBHIGKEY=Y, U/BL will return the highest key in the index rather than high values. In this situation the value returned in the recnum field is still 0.

In an index with duplicates, the KFIND command will only find the first key of a series of duplicates. The KNEXT command can be used to find later keys in the series.

Dependant on the setting of the environment variable BBLASTKEy when the index was created, A KFIND command for a duplicate key will return either the first (BBLASTKEY=Y) or the last example of the key added to the index.

Refer to the section on the KADD command for an explanation of when to use lf_number and when to use desc$.

Example

The files have been LOPENed and strings dimensioned:

00050 INPUT "Enter key of record...",KEY$

00060 IF KEY$="" THEN GOTO 0200

00080 KFIND 1,BUF$,KEY$,RECNO

00090 IF RECNO<=0 THEN

00100 PRINT "No record exists"

00110 ELSE

00120 LREAD FILE[2,RECNO],RECORD$

00130 PRINT RECORD$

00140 END IF

00150 INPUT "Enter key of another record...",KEY$

00160 GOTO 00060

00200 CLOSE

00999 END

See also

BB2048

BBKCHAN

BBHIGHKEY

KADD

KDEL

KNEXT

KPREV


KNEXT

KNEXT ---------- Retrieve the next key in an index file

Type

U/BL statement and command

Syntax

Format 1: | KNEXT file_id,buffer$,key$,recnum
Format 2: | KEXT desc$,buffer$,key$,recnum

Arguments

desc$ | A string variable containing details of the index file.
file_id | The logical file number used to LOPEN the index file, or if the environment variable BBEXTENSION is set to SDOS or the environment variable BBKCHAN=Y, the channel number on which the file is OPEN.
buffer$ | A string variable with a length of at least 544 bytes
key$ | A string variable the length of the index key, and which receives the key.
recnum | A numeric variable which receives the record pointer, or zero if the end of the index is reached.

Description

The KNEXT command returns in key$ the key in an index immediately after the last key accessed by a KFIND, KPREV or earlier KNEXT statement. The key's record pointer is returned in recnum. The KNEXT command uses the buffer$ set up by previous statements, so the buffer$ must not have been modified.

If there is no key after the last accessed key, KNEXT returns a key consisting of high values and sets the record pointer to zero. Another KNEXT causes an end-of-data error.

To use KNEXT, first use KFIND. KADD or KDEL will also set up the current position in the index for KNEXT. Any number of KNEXTs can follow KFIND, and any number of KPREVs can be interspersed with them. Each index file being accessed should have a separate buffer$.

Refer to the section on the KADD command for an explanation of when to use lf_number and when to use desc$.

To find a key which has duplicates, use KFIND to access the first key of the series and then use KNEXT to scan through the series. Dependant on the setting of the environment variable BBLASTKEY that is in use, duplicate keys will either be returned with the first key added being found last (BBLASTKEY not set or set to N) or with the first returned key being the first key that was added. To read an entire index sequentially, use KFIND with a null-value key, and then use KNEXT until the end of the index is reached.

Example

00005 REM Read entire file in index order (perhaps for a report)

00010 DIM KEY$[6],BUF$[544],LFTABL$[52]

00020 LET LFTABL$,KEY$=FILL$[0]

00030 LOPEN FILE[1,KEY$],"INDEXFILE"

:

00050 KFIND 1,BUF$,KEY$,RECNO

00060 IF RECNO=0 THEN GOTO 00110

00070 LET RECNO=ABS(RECNO)

00080 GOSUB 00200 : READ AND PROCESS DATA RECORD

00090 KNEXT 1,BUF$,KEY$,RECNO

00100 GOTO 00060

00110 CLOSE

00999 END

See also

BB2048

BBKCHAN

BBLASTKEY

$KPREV

KADD

KDEL

KFIND

KPREV


KPREV

KPREV ---------- Locates the previous key in an index after a KFIND

Syntax

Format 1: | KPREV file_id,buffer$,key$,recnum
Format 2: | KPREV desc$,buffer$,key$,recnum

Arguments

desc$ | An index file descriptor string, in the same form used by the KFIND command.
file_id | The logical file number used to LOPEN the index file, or if the environment variable BBEXTENSION is set to SDOS or the environment variable BBKCHAN=Y, the channel number on which the file is OPEN.
buffer$ | The same buffer$ string that was used in the KFIND command which preceded this KPREV.
key$ | A string variable which receives the key. It must be of the same length as the key.
recnum | A numeric variable which receives the record pointer.

Description

The KPREV command returns in key$ the key in an index immediately before the last key accessed by KFIND, KNEXT or an earlier KPREV command. The key's record pointer is returned in recnum. The KPREV command uses the buffer$ set up by previous statements, so the buffer$ must not have been modified. If there is no key before the last accessed key, the KPREV command fills key$ with null characters and places zero in recnum. Another KPREV command causes an end-of-data error.

To use the KPREV command, you must first issue the KFIND command. The KADD or KDEL commands also set up the current position in the index for the KPREV command. Any number of KNEXT commands can follow the KFIND command, and any number of KPREV commands can be interspersed with them. Each index file being accessed should have a separate buffer$.

Refer to the section on the KADD command for an explanation of when to use lf_number, and when to use desc$.

The KPREV command works only with 2048-byte indexes, or with 512-byte indexes without duplicates. Users of 512-byte indexes with duplicates must upgrade to 2048-byte indexes if they want to use KPREV.

The KPREV command takes roughly ten percent longer than the KNEXT command on average; however, this figure depends on the index structure, and worsens with longer keys.

$KPREV is a synonym for KPREV.

Example

This program fragment finds the record with a value just less than or equal to the given string.

01850 REM Returns a key greater than or equal

01900 KFIND 1,B$,PARTKEY$,RECNUM

01950 REM No exact match

02000 IF RECNUM<0 THEN KPREV 1,B$,PARTKEY$,RECNUM

02100 IF RECNUM THEN

02200 LREAD FILE[2,RECNUM],REC$

02230 PRINT REC$

02300 ELSE

02400 PRINT "No suitable record "

02500 END IF

See also

BB2048

BBKCHAN

BBLASTKEY

$KPREV

KADD

KDEL

KFIND

KNEXT


$L

$L ------------ Toggles physical line numbers

Type

U/BL command.

Syntax

$L

Description

The $L command toggles physical line numbers on and off. If a program has very few numbered lines, editing at the * prompt can be quite difficult. $L toggles on the physical line numbers which can then be used to LIST program lines for editing.

If $L is typed at the U/BL * prompt, then any subsequent LISTs will work on the physical line numbers.

When physical line numbers are on, the U/BL prompt changes to a percent sign (%). This can be configured via the environment variable BBPROMPTP. The physical line numbers will appear on the screen in low intensity (dim) to differentiate them from program line numbers.

If you are in $L mode, and LIST a physical line that does not exist, then the last line of the program will be LISTed. For example, if the following program is in memory:

1 00010 PRINT 10

2 00020 PRINT 20

3 00030 PRINT 30

Typing LIST 1,999 would LIST the whole program and typing LIST 999 would only list the third physical line, labelled 00030.

Example

* list

PRINT "my heart aches"

PRINT "and a drowsy numbness"

PRINT "pains my sense"

* $l

% list

  1 PRINT "my heart aches"

  2 PRINT "and a drowsy numbness"

  3 PRINT "pains my sense"

% list 2

  2 PRINT "and a drowsy numbness"

% $l

* list

  PRINT "my heart aches"

  PRINT "and a drowsy numbness".  PRINT "pains my sense"

See also

.A | .C | .E
.I | .M | .N
.NA | .NB | .P
. | BBPROMPTL | BBPROMPTM
BBPROMPTN | BBPROMPTP | LIST


LEN

LEN ---------- Returns the number of characters in a string

Type

U/BL function.

Syntax

LEN(str$)

Arguments

str$

A DIMensioned string variable, substring or string literal.

Description

The LEN function returns the actual size of a string, not the maximum size it has been DIMensioned to. It counts all the characters in a string including nulls, spaces and special characters. If the string is empty, the LEN function returns zero.

Example

* dim x$[100]

* print len(x$)

0

* x$="hello"

* print len(x$)

5

* x$=fill$[65]

* print len(x$)

100

* print len(x$[1,5])

5

* print len("Season of mists and mellow fruitfulness")

39


LET

LET --------- Assigns the value of an expression to a variable

Type

U/BL statement or command.

Syntax

[LET] var [,var]...=expr [\ var[,var]...=expr]..)

Arguments

var | Any numeric or string variable.
expr | Any numeric expression, or any string expression if var is a string.

Description

The LET command calculates the value of an expression and stores the result in a variable. Numeric variables are created if they do not already exist, but string variables must first be DIMensioned. The keyword LET is optional, but if it is missing U/BL adds it when it formats lines.

Substrings should not be assigned to the original string unless the substring begins at the start of the original string. For example,

LET X$=X$[2,5]

results in the string being corrupted.

A string variable can be set to the value of a number or numeric variable. It can also be set to several smaller strings or expressions by using commas as concatenation operators.

Examples

* a=1

* print a

1

* let b=a+3

* print b

4

* c=b-a \ d=a-b

* print c,d

3 3

* dim x$[10], y$[10]

* x$="hello"

* print x$

hello

* a,b,c = b+1

* print a,b,c

555

* 50 a=3 \ b=2 \ c$[1,2]=x$

* list

00050 LET A=3 \ B=2 \ C$[1,2]=X$


LIST

LIST ---------- Lists all or part of a program to the screen, a file or a device

Type

U/BL command.

Syntax

Format 1: | LIST [start] [,finish] [filename]
Format 2: | LIST [start] [TO finish] [filename]
Format 3: | LIST [start] [,]
Format 4: | LIST [start] [TO]

Arguments

start | Line to begin LISTing at. If start is not followed by a comma or TO, only one line is LISTed, and that line must exist, otherwise if the line doesn't exist LISTing starts at the first line following start.
finish | Line to end LISTing at
filename | A string expression containing a filename or a spooled device name. The full pathname can be specified.

Description

The LIST command writes the program in memory, or selected parts of it, to the screen. When a filename (or device name) is specified in the filename parameter, the LIST command writes the program, or selected parts of it, to the file or spooled device. The file must not previously exist. The file created is a text file, which can be ENTERed into U/BL again.

If the optional start or finish parameters are specified they constrain the LIST statement to display only those lines within the specified range between the starting point and the specified finish (or end of the program). The start or finish parameters must either be the name of a label in the program or a number referencing a line in the program. When specifying the start or finish parameters with numbers, U/BL will either interpret these as logical line numbers (where the source is line numbered and the numbers identify individual lines in the program) or physical lines (the physical position of the line within the program). U/BL's interpretation depends on what state it is currently running in. By default (unless BBNEWLIST=Y) U/BL will start up in a mode which interprets the line references as logical line numbers (program line numbers). Using the $L command or if U/BL is invoked with BBNEWLIST=Y in its environment causes U/BL to interpret line references as specifying physical locations in the source (the physical line number).

If the start or finish parameters are not specified, then the LIST command writes the whole program. The LIST filter causes programs LISTed to the screen to be displayed one page at a time. The following prompt is displayed at the end of each screen full, if another page follows:

  Press Any Key to Continue (q to quit)

Entering q returns the user to the U/BL prompt. This feature can be controlled with the BBPAGE environment variable.

U/BL also provides the alternative LISTH command which performs the same functionality as the LIST command but additionally outputs a set of header information with the source.

If the BBSOURCE environment variable is set and a program is LISTed to a filename, the file will always be placed in the first directory specified by BBSOURCE. If LISTing to a spooled device such as a printer, the environment variables BBSPOOL and optionally BBTYPE must be set up correctly.

Examples

1. Simple examples demonstrating how to use the LIST command.

* list

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

* list 20

00020 PRINT "Hello"

* list 20,30

00020 PRINT "Hello"

00030 END

* list to 20

00010 REM This is a test program

00020 PRINT "Hello"

2. Using the LIST command to write the program in memory to a text file.

* list "myfile

See also

BBNEWLIST

BBPAGE

BBPROMPTP

BBPROMPTL

BBPTYPE

BBSLITCH

BBSOURCE

BBSPOOL

$L

LISTH


LISTBOX

LISTBOX ---------- Create a list box

Type

Windows Object Command

Syntax

LISTBOX(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, MODE [, STAT])

Arguments

ID | The unique handle used to identify the object
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT$ | The initial text to be placed in the list box. This has a limit of 255 characters.
MODE | Specifies how the statement (and subsequently, the object) will work.
STAT | Optional status return.

Description

This function creates a list box. The list box object has a unique ID handle, which is used to identify the object in subsequent Windows modifier commands. The list box is created at position ROW, COL and has a size of HEIGHT, WIDTH.

The TEXT$ parameter determines the initial contents of the list box and consists of a set of values separated by the pipe symbol '|'. Unlike objects created by the COMBOBOX statement, list boxes have no item initially selected when they are defined. Once the object has been created, new items can be added to the list box using the ADDITEM statement, and redundant items can be deleted using the DELITEM statement. As the size of the TEXT$ parameter on the LISTBOX statement is limited to 255 characters if you need more characters than this, you must create the LISTBOX with a subset of the required options (within the 255 character limit) and use ADDITEM to subsequently add the extra items.

The MODE parameter determines various options of how the list reacts to mouse clicks and key presses. As well as the Standard Windows Object Flags, the following additional options can be set:

Value

Description

32

This will automatically sort the items in the list box. However, this will make it difficult to refer to an item by index later.

64

The list box will not have a vertical scroll bar

128

The list box will send a message @^n;2; (where 'n' is the handle of the Windows object) back to U/BL when an item is double clicked. If the NOTIFYSELCHANGE flag is used in conjunction with this flag, U/BL will receive a message of @^n;1;@^n;2; ('n' being the handle of the object). This is due to double clicking re-selecting the item even if it was the item already selected.

256

The list box will send a message @^n;1; back to U/BL when the user changes the current selection, where 'n' is the handle of the Windows object

512

LISTBOXes can be converted into multi-column ones by the addition of a style 512. Text added to the list box should be separated by tab <9> characters, and SETTEXT can be used to set the widths of the columns. For example:

SETTEXT(1,"10,20,30")

will set the width of the first column to 10 average character widths, and so on. These messages can be used to tell the program to extend the list of available selections in the list box (for instance the user is effectively telling the program that the option they are looking for lies before/after the options currently in the list box). This facility prevents the program from initially having to populate a list box with all the possible options, thus allowing for improved performance.

1024

Setting the MODE parameter to this value will result in the message @^n;3 being issued if you attempt to move past the beginning of a list box. The message @^n;4 will be issued if you attempt to move past the end of a list box.

This can be used by a U/BL program to repopulate the listbox with more options so providing a "next-page" like functionality.

2048

The list box will send a message @^n;2; (where 'n' is the handle of the Windows object) back to U/BL when ENTER is pressed.

See Also

ADDITEM

DELETEWO

DELITEM

Error codes

ENABLEWO

GETNUMBER

GETTEXT

SETFOCUS

SETNUMBER

SETTEXT

SHOWWO

Standard Windows Object Flags


LISTH

LISTH ---------- Lists all or part of a program with a header

Type

U/BL command.

Syntax

Format 1: | LISTH [start] [,finish] [filename]
Format 2: | LISTH [start] [TO finish] [filename]
Format 3: | LISTH [start] [,]
Format 4: | LISTH [start] [TO]

Arguments

start | Line number to begin LISTing at. If start is not followed by a comma or TO, only one line is LISTed, and that line must exist, otherwise if the line doesn't exist LISTing starts at the first line following start.
finish | Line number to end LISTing at
filename | A string expression containing a filename or a spooled device name. The full pathname can be specified.

Description

The LISTH command behaves in exactly the same way as the LIST command, except that three header lines are written giving the account name, date, time and program name. If the program has not been previously LOADed, SAVEd or REPLACEd, the program name defaults to a name of SCRATCH. The file can be re-ENTERed into Basic.

If the optional start or finish parameters are specified they constrain the LISTH statement to display only those lines within the specified range between the starting point and the specified finish (or end of the program). The start or finish parameters must either be the name of a label in the program or a number referencing a line in the program. When specifying the start or finish parameters with numbers, U/BL will either interpret these as logical line numbers (where the source is line numbered and the numbers identify individual lines in the program) or physical lines (the physical position of the line within the program). U/BL's interpretation depends on what state it is currently running in. By default (unless BBNEWLIST=Y) U/BL will start up in a mode which interprets the line references as logical line numbers (program line numbers). Using the $L command or if U/BL is invoked with BBNEWLIST=Y in its environment causes U/BL to interpret line references as specifying physical locations in the source (the physical line number).

If the start or finish parameters are not specified, then the LIST command writes the whole program. The LISTH filter causes programs LISTed to the screen to be displayed one page at a time. The following prompt is displayed at the end of each screen full, if another page follows:

  Press Any Key to Continue (q to quit)

Entering q returns the user to the U/BL prompt. This feature can be controlled with the BBPAGE environment variable.

If the BBSOURCE environment variable is set and a program is LISTHed to a filename, the file will always be placed in the first directory specified by BBSOURCE. If LISTHing to a spooled device such as a printer, the environment variables BBSPOOL and optionally BBTYPE must be set up correctly.

Example

* listh

: ACCOUNT DATE TIME PROGRAM

: AAMHHB 4-AUG-92 9:59:25 testprog

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

See also

BBNEWLIST

BBPAGE

BBPROMPTP

BBPROMPTL

BBPTYPE

BBSLITCH

BBSOURCE

BBSPOOL

$L

LIST


LOAD

LOAD ---------- Loads a SAVEd program into memory

Type

U/BL command.

Syntax

LOAD filename

Arguments

filename

A string expression containing a filename. The full pathname can be specified.

Description

The LOAD command clears the current program and data from memory, and reads the U/BL SAVE file specified in the filename parameter, from disk. The file must be in U/BL's SAVE format. The loaded program is not executed.

If the BBEXTN environment variable is set, the specified ".extension" will be added to the filename, if it has no extension already.

Examples

1. A simple example showing how to use the LOAD command to load a file called TEST.

* load "test

* list

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

2. Setting the BBEXTN environment variable to '.SV' (BBEXTN=.SV), will result in the following LOAD command looking for a file called, TEST.SV before looking for a file called TEST.

* load "test

3. The following LOAD command will only look for a file called TEST.PR.

* load "test.pr

See also

ENTER


LOCK

LOCK ---------- Place a LOCK on a file

Type

U/BL statement and command.

Syntax

Format 1: LOCK id,filename,start,recsize{,code}

Format 2: LOCK id,lf_number,recnum{,code}

Format 2 is not supported if the environment variable BBEXTENSION=SDOS.

Arguments

id | A numeric expression to identify the lock. This number is local to the job. It can range from 1 to 32767. A lock id of 32767 should be avoided as this identifier is used internally.
filename | Either a logical or physical filename.
start | A numeric expression for either the logical or physical starting byte number of the area to be locked.
recsize | A numeric expression for the number of bytes to be locked.
code | A numeric variable which should be set to the time to wait for any existing LOCK to become free. The time should be specified in tenths of seconds. The code variable receives the result of the LOCK.
lf_number | A numeric expression which corresponds to the logical file number of a previously LOPENed type "D" or "L" data file.
recnum | The record number of a logical record to be locked.

Description

A LOCK is a convention used to prevent two or more users from updating the same record at one time. Before accessing a record which might be used by others, a LOCK should be attempted. If the LOCK succeeds, the record is available for use, and the value -1 is placed in the code variable. An unsuccessful LOCK results in an error code being placed in code.

A LOCK does not prevent a user from accessing the record, it is only a warning. A LOCK will fail if any part of the area to be LOCKed is already LOCKed by a different process. If no code is specified, the program will wait indefinitely if the area specified is already LOCKed. This is not usually desirable.

Each site should decide on a convention of using logical or physical filenames and starting byte numbers. If the same area of a file is referred to in two different ways, both LOCKs will succeed and the purpose of LOCKing will be defeated. A LOCK remains in effect until an UNLOCK is performed or the process which issued it terminates.

If type-L logical files and the GETREC statement are used, record 0 of the data file should not be LOCKed manually, as GETREC does its own locking of this record.

Use the U/BL Monitor utility to display the locks currently in force.

The BBLOCKDG environment variable allows the return from LOCK to be controlled. By default the LOCK statement returns -1 for success, but if the user sets BBLOCKDG=N then 0 is returned for success.

Example

01000 REM Found record we want to process

01010 LET CODE=0 : Time to wait if record is locked

01020 LOCK 1,2,RECNO,CODE

01030 IF CODE=-1 THEN : Successful lock

01040 GOSUB 02000 : Process record

01050 UNLOCK 1 : Unlock it

01060 ELSE

01070 PRINT "Someone else already has their mitts on that one"

01080 END IF

See also

GETREC

UNLOCK

BBLOCKDG


LOGOFF

LOGOFF ---------- Closes an active data source

Type

SQL Access Statement

Syntax

LOGOFF([CONN$][,STAT])

Arguments

CONN$ | The connection identifier. This argument is optional, it is only required in programs that use multiple concurrent connections. If this argument is specified and the connection exists it will be disconnected, if it does not exist an error status of 2 will be returned. If the connection identifier is not specified then all current connections will be disconnected.
STAT | Optional status return

Description

The LOGOFF command closes the active SQL Access connection (which was initialized by a preceding LOGON statement). A LOGOFF deletes any cursors (as defined by a previous SQL statement) associated with the connection. Any output from these cursors that has not already been FETCHed will be discarded.

For SQL Access connections to data sources that support transactional processing, a LOGOFF statement performs an implicit COMMIT statement. To discard any pending output, a ROLLBACK statement must be used prior to the LOGOFF.

For full documentation of U/BL's SQL Access functionality, refer to the SQL Access Commands section.

Example

LOGOFF (CONN$, STAT)

IF STAT <>0 THEN

GOSUB @Process_SQL_Error

END IF

See Also

COMMIT

FETCH

LOGON

ROLLBACK

SQL


LOGON

LOGON ---------- Establishes a connection to a remote data source

Type

SQL Access Statement

Syntax

LOGON(DATASRC$, USER$, PASSWD$ [,CONN$] [,STAT])

Arguments

DATASRC$ | Specifies the data source name (DSN), that U/BL must log on to.
USER$ | The username to connect as.
PASSWD$ | The password for the user
CONN$ | The connection identifier. This argument is optional. It is a string variable or constant with a maximum length of 20 characters. It is used to identify a connection in programs where there may be multiple concurrent connections. This argument is not required if only one connection is current at any time. If this argument is not specified then any existing connection will be disconnected automatically when LOGON is executed. If the connection identifier is specified and that connection is already current an error status of 3 will be returned. If the maximum number of concurrent connections (10) is exceeded, the return status will be 4.
STAT | Optional status return.

Description

The LOGON command establishes a connection to the SQL Access datasource named by the DATASRC$ parameter. For Windows versions of U/BL, this parameter must be the name of a system ODBC data source. For UNIX implementations it must be the name datasource as listed in U/BL's ODBC_INI configuration file. If an existing connection is active, the LOGON statement performs an implicit LOGOFF before establishing the new connection.

The USER$ and PASSWD$ parameters allow the command to specify a personality for the U/BL job to attach to the SQL Access datasource. This personality is only used when the remote datasource is configured for user authentication. By default, for Transoft's U/SQL Servers, the username and password information is ignored unless host user validation is enabled (refer to Chapter 5 of the U/SQL Client-Server Configure & Use manual).

For full documentation of U/BL's SQL Access functionality, refer to the SQL Access Commands section.

Example

In this example the data source name is hard-coded as Booksw32.udd. The user name and password are set to "". The coding contains an error check, which forces a call to a routine that would handle any SQL Access problems. It is recommended that the error handling routine include the use of the SQLERR command in order to provide a more meaningful response.

00100 DIM DSN$[30], USER$[50], PWD$[50],CONN$[10]

00110 LET CONN$="BBISAMBOOKS"

00120 LET DSN$="Booksw32.udd"

00130 LET USER$=""

00140 LET PWD=""

00160 LOGON (DSN$,USER$,PWD$,CONN$,STAT)

See Also

COMMIT

LOGOFF

SQL

SQLERR


LOOP

LOOP ---------- To define the end of a DO WHILE or a DO UNTIL instruction

Type

U/BL statement.

Syntax

LOOP

Description

The LOOP statement defines the end of a DO WHILE or DO UNTIL loop. It is similar to an END IF statement, but also implies a jump back to a point in front of the statement immediately following the DO WHILE or DO UNTIL statement. When this jump has taken place, the logical expression is tested to determine whether the statements should be executed again.

See DO WHILE and DO UNTIL for a more information on how this statement works.

Possible errors

BASIC error #91 (compiler error) - if there was no preceding DO WHILE or DO UNTIL.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

PROCESS AN INDEX FILE

  KEY$=" "

  KFIND CH, B$, KEY$, RN

  RN=ABS (RN)

200 DO WHILE RN <>0

  RREAD FILE (DC, RN) ,REC$

  GOSUB 2000 :PROCESS THIS RECORD

  KNEXT CH, B$, KEY$, RN

  LOOP

  PRINT "END-OF-INDEX". PROCESS COMPLETE."


LOPEN

LOPEN ----------- Opens a logical file

Type

U/BL command and statement

Syntax

LOPEN [e,]FILE(lnum,dummy[,flgs]),lname

LOPEN [e,]FILE(lnum,ch[,flgs]),lname,ftype,recl[last[,oH]]

Arguments

e

A numeric variable which receives an error code if the LOPEN fails.

lnum

A numeric expression for the logical file number which will be used to refer to this logical file in future.

dummy

A string variable. This is ignored by U/BL.

flgs

A numeric expression which determines whether the logical file is to be opened exclusively, and whether locking should take place.

lname

A string expression containing the name of the logical file.

ch

The channel used to OPEN the physical file which contains this logical file.

ftype

A string expression containing:

  • "D" -- for a direct file

  • "I" -- for an index file

  • "L" -- for a linked file

  • "Q" -- for a queue file.

recl

A numeric expression containing the record length of the logical file.

last

A numeric expression containing the last record number allowed in the logical file. This argument is only required for index files. It defaults to 167772/15 for other file types (see the section on the BBLOPEN environment variable).

oH

A numeric variable which represents the byte position in the physical file where the logical file begins.

Description

The LOPEN command is used to establish I/O to a logical file prior to any logical I/O statements relating to that file. The first syntax shown above is used for a logical file created using the Logical File Utility (LFU).

The second syntax is used when a physical file has been opened and the logical I/O statements are to be used with it.

The flgs parameter only affects link and index files. Bit 0 should be set on to disable locking, otherwise GETREC, DELREC, KADD, KDEL and KFIND commands use locks during their operation. Bit 1 should be set on for an exclusive open. The default if flags are not specified is for the file to be shared and locking to occur.

Any program using logical I/O must DIMension a string variable called LFTABL$ with a length of at least 26 times the highest logical file number used. LFTABL$ should be null filled at the beginning of the program. U/BL maintains LFTABL$ itself to define each logical file. Each 26 bytes in LFTABL$ have the following structure:

Field | Position | Length
Channel number | 1 | 2
Starting byte | 3 | 4
Flags | 7 | 2
Logical filename | 9 | 10
Record length | 19 | 2
Last record number | 21 | 4
File type | 25 | 1
Next volume link | 26 | 1

There is no LCLOSE statement. A CLOSE statement without an argument will close the physical file or files associated with any logical files. LFTABL$ must be reinitialized to null characters before logical file channels can be reused.

The BBLOPEN environment variable can be used to determine how the optional "last record number" parameter on an LOPEN statement reacts when it encounters a zero or no parameter.

The BBLFTABOVR environment variable stops the LOPEN statement from checking that the corresponding logical file number in the LFTABL$ is in use (not NULL filled) before allowing the open to take place. Normally, if the record in LFTABL$ is occupied, the LOPEN statement generates an error regardless of whether the record is in use by a logical file or not.

Examples

1. LOPENing a file created by LFU.

00010 DIM LFTABL$[26],BUF$[1]

00020 LET LFTABL$=FILL$[0]

00030 LOPEN FILE[1,BUF$],"LOGIFILE1"

2. Creating and LOPENing a physical file as an index.

00010 DIM LFTABL$[26],T9$[2048]

00020 LET LFTABL$=FILL$[0]

00030 OPEN FILE[0,10],"PHYSIFILE1"

00040 LOPEN FILE[1,0],"LOGIFILE2","I",512,100

00050 REM Now set up variables for LINITINDEX

00055 REM Set YY = file number used in the LOPEN statement

00060 LET YY%=1 :

00070 LET X=8 : KEY LENGTH

00080 LET Y=0 : NO DUPLICATE KEYS

00090 LET Z=75 : PERCENTAGE BLOCKING FACTOR

00095 REM 2048 byte blocks. T9$ is DIM'ed to the block size

00100 LET YY=1

00110 GOSUB 7700 : LINITINDEX.SL

See also

BBLFTABOVR

BBLOPEN

LREAD

LWRITE


LOWERCASE

LOWERCASE ---------- To SET the value of the UPPERCASE terminal control flag

Type

U/BL statement.

Syntax

LOWERCASE

Description

The LOWERCASE statement sets the value of the UPPERCASE flag to 1. This means that lower case characters are NOT automatically changed to upper case.

It is equivalent to the STMA 6,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


LREAD

LREAD ---------- Reads a record from a logical file

Type

U/BL command and statement.

Syntax

LREAD FILE (lf_num, recnum), record$

Arguments

lf_num | The logical file number used to LOPEN this logical file.
recnum | A numeric expression which represents the record number to read.
record$ | A string variable which receives the contents of the record read.

Description

The LREAD FILE command reads a single record from a previously LOPENed logical file and places the binary data into the record variable specified. Only the number of bytes defined as the logical file's record length (either in the LFU LCREATE statement or at the time the file was LOPENed) are read. If the record$ parameter is too short, an error occurs, while if it is too long it is not be completely filled.

Reading a record which has never been written results in the record$ parameter containing null values.

Example

* list

00010 DIM LFTABL$[26],NAME$[20],DATE_PAID$[9],DEBTOR$[52],EOF$[52]

00020 LET LFTABL$,EOF$=FILL$[0]

00030 LOPEN FILE[1,DEBTOR$],"DEBTORS"

00040 PRINT "DEBTORS' LISTING"

00050 PRINT "NAME","AMOUNT OWED","DATE OF LAST PAYMENT"

00060 LREAD FILE[1,1],DEBTOR$

00070 IF DEBTOR$=EOF$ THEN GOTO 00140

00080 UNPACK "CA20@40LC",DEBTOR$,STATUS%,NAME$,OWING,JDATE_PAID

00085 IF STATUS% THEN : RECORD IS NOT DELETED

00090 LET DATE_PAID$=$DATE$(JDATE_PAID,0,3)

00100 PRINT NAME$,OWING,DATE_PAID$

00110 LET TOT_DEBTORS=TOT_DEBTORS+1 \ TOT_OWING=TOT_OWING+OWING

00115 END IF

00120 LREAD FILE[1,TOT_DEBTORS+1],DEBTOR$

00130 GOTO 00070

00140 PRINT TOT_DEBTORS;" on file, owing a total of ";TOT_OWING

00150 CLOSE

00160 END

See also

LOPEN

LWRITE


LSTRIP

LSTRIP ---------- Removes any unused line numbers in a program

Type

U/BL command.

Syntax

LSTRIP

Description

The LSTRIP command removes any unused line numbers in a program. Any line numbers that are not referenced by a GOTO, GOSUB or PACK command are removed.

If the program being stripped is CHAINed to via a CHAIN "PROGNAME" THEN GOTO line_number statement, then care must be taken since the target line number could be stripped, which would result in an "ERROR 13 - Line number" run-time error.

Program lines which refer to other line numbers must also be checked to ensure that the line numbers being referred to are referenced so that LSTRIP does not remove them. For example, any checks on SYS(20) (line number of the last error or IKEY) must be checked for by the user, and worked around by putting a dummy GOTO statement in at some point in the program:

* list

00010 ON ERR THEN GOTO 00100

00020 OPEN FILE[0,3],"TEST"

00090 STOP

00100 IF SYS(20)=20 THEN GOSUB 01000

:

This program does not work if stripped, since SYS(20) refers to an unreferenced line number. The work around here is to insert a dummy GOTO line after line 90 (so that the dummy GOTO is never executed):

* list

00010 ON ERR THEN GOTO 00100

00020 OPEN FILE[0,3],"TEST"

00090 STOP

00095 GOTO 00020 : Dummy GOTO so LSTRIP can be used

00100 IF SYS(20)=20 THEN GOSUB 01000

:

* lstrip

* list

ON ERR THEN GOTO 00100

00020 OPEN FILE[0,3],"TEST"

STOP

GOTO 00020 : Dummy GOTO so LSTRIP can be used

00100 IF SYS(20) =20 THEN GOSUB 01000

:

Setting the environment variable BBSTRIPLNO to Y causes any program ENTERed to have its line numbers stripped automatically.

Example

* list

00005 PRINT "In the mainline"
00010 GOSUB 00100 : First subroutine
00020 PRINT "Back in the mainline"
00030 GOSUB 00200 : Second subroutine
00040 PRINT "Mainline finishing now"
00050 END

00100 REM First subroutine
00110 PRINT "This is the first subroutine executing"
00120 PRINT "This is the first subroutine ending"
00130 RETURN

00200 REM Second subroutine
00210 PRINT "This is the second subroutine executing"
00220 GOSUB 00100 : First subroutine
00230 PRINT "This is the second subroutine ending"
00240 RETURN

* lstrip

* list

  PRINT "In the mainline"
  GOSUB 00100 : First subroutine
  PRINT "Back in the mainline"
  GOSUB 00200 : Second subroutine
  PRINT "Mainline finishing now"
  END

00100 REM First subroutine
  PRINT "This is the first subroutine executing"
  PRINT "This is the first subroutine ending"
  RETURN

00200 REM Second subroutine
  PRINT "This is the second subroutine executing"
  GOSUB 00100 : First subroutine
  PRINT "This is the second subroutine ending"
  RETURN

See also

BBNOUSCORE

BBSTRIPLNO


LWRITE

LWRITE ---------- Write a record to a logical file

Type

U/BL command and statement.

Syntax

LWRITE FILE (lf_num, recnum), record$

Arguments

lf_num | The logical file number used to LOPEN this logical file.
recnum | A numeric expression which represents the record number to write.
record$ | A string variable which contains the record to be written.

Description

The LWRITE command writes a single record to a previously LOPENed logical file using the data in the record variable specified.

If the variable is shorter than the logical file's record length (defined either in the LFU LCREATE statement or at the time the file was LOPENed), the output is padded with nulls. If the variable is too long, an error occurs.

By default BBASIC produces an error if an attempt is made to perform an LWRITE of more data than the logical record can hold. Setting the BBLWRITETRUN environment variable to Y causes U/BL not to produce the error if LWRITE tries to write a string with a length greater than the record length of the logical file. Instead the data written is truncated to the record length.

Example

The following program reads a series of record numbers and payments from a sequential file and updates a logical file of debtors:

00010 DIM LFTABL$[26],DEBTOR$[52]

00020 LET LFTABL$=FILL$[0]

00030 OPEN FILE[0,13],"PAYMENTS"

00040 LOPEN FILE[1,DEBTOR$],"DEBTORS"

00050 INPUT FILE[0],RECNO,PAYMENT : READ FIRST PAYMENT

00070 IF EOF[0] THEN GOTO 00170 : UNTIL END OF PAYMENTS FILE

00080 LREAD FILE[1,RECNO],DEBTOR$ : READ APPROPRIATE DEBTOR RECORD

00090 UNPACK "@40L",DEBTOR$,OWING : EXTRACT AMOUNT OWING

00095 IF PAYMENT THEN : ONLY UPDATE FILE IF PAYMENT>0

00100 LET OWING=OWING-PAYMENT : UPDATE

00110 PACK "@40LC",DEBTOR$,OWING,SYS(152) : REPACK AMOUNT OWING,DATE

00120 LWRITE FILE[1,RECNO],DEBTOR$ : REWRITE DEBTORS FILE

00125 END IF

00140 INPUT FILE[0],RECNO,PAYMENT : READ NEXT PAYMENT

00150 GOTO 00070

00170 CLOSE FILE[0]

00180 END

See also

BBLWRITETRUN

LOPEN

LREAD


$M

$M ------------ Display information associated with IPC calls

Type

U/BL command.

Syntax

$M queue_id

Arguments

queue_id

The message queue ID

Description

The $M command takes as arguments the message queue ID. Use the $Q command to determine the queue ID for a particular port. The display information includes:

  • Owner ID

  • Current number of bytes on the queue

  • Current number of the last message on the queue

  • PID of the last message sent

  • PID of the last message received

These two commands, $M and $Q, are used to display information associated with IPC calls.

See also

$Q


$MDE

$MDE --------- Returns the mode in which a channel is open

Type

U/BL function.

Syntax

$MDE(channel)

Arguments

channel

A numeric expression representing a channel.

Description

The $MDE function is used to determine the mode in which a file is open. It can be used for diagnostic purposes. The $MDE function can be used either as a statement or in command mode.

Example

* list

0010 $TURN_OFF(MODE15)

0020 OPEN FILE[1,5],"TEST"

0030 PRINT "Without mode 15 the mode is";$MDE(1)

0040 CLOSE

0050 $TURN_ON(MODE15)

0060 OPEN FILE[1,5],"TEST"

0070 PRINT "With mode 15 the mode is";$MDE(1)

0080 CLOSE

* run

Without mode 15 the mode is 5

With mode 15 the mode is 15


MACTION

MACTION ----------- Display the specified menu

Type

U/BL command and statement.

Syntax

MACTION(mnam$,act[,stat[,code$][,item]])

Arguments

mnam$ | The name of the menu.
act | Returns the menu item number selected (where 1 is the first item) or any appropriate MFKEY exit value. 0 is returned if the menu is aborted. If act is set to a valid option number before the menu is executed, then the menu will start at that option.
stat | Receives the error code.
code$ | Receives either the menu item's text or if an appropriate MFKEY was actioned, the erroneous text entered by the user to cause the menu to exit.
item | Returns the number of the menu item the user was on when an MFKEY exit was taken.

Description

The MACTION statement displays the previously created (by MCREATE) menu specified in the mnam$ parameter and waits for the user's choice. You can only choose what is in the menu. You are not allowed to enter anything else. If the act variable is set before the MACTION statement is executed, then the menu starts at that option. The act variable is the menu item number selected or the exit code associated with any actioned MFKEY. Once this is known an ON ACT GOTO or GOSUB can be performed.

The additional variables code$ and item return more verbose information about the state of the menu when it was exited. The code$ variable receives either the text of the menu item selected or if MFKEY 21 0r 22 has been actioned, the illegal text or function key typed by the user, and the item variable returns the number (starting from 1) of the item selected at the time the menu was exited. These may then be placed in the user's input buffer via an STME 27 statement.

They are typically used when you Hot Key from, say, a maintenance program to a program showing a code look up in the form of a Pull Down menu. You can then select the code you require and 'cut' it from the window and 'paste' it back in the field you left in the maintenance program.

Example

The main program has the following lines of code:

01000 $HOT 1, "!CODEPROG"

01010 INPUT USING "",........,X$

Then the Hot Key 1 is hit and in a window appears the CODEPROG program:

00100 REM Hot Keyed Program

:

00200 CHFREEZE(CHAN$, STAT)

:

00300 MACTION("CODES",ACT,STAT,CODE$,ITEM)

00310 IF ACT>0 THEN

00320 LET CODE$[0]=ITEM

00330 STME 27,ER,CODE$,1

00340 END IF

:

00400 CHREOPEN(CHAN$,STAT)

and the contents of code$ appears as the entry of INPUT USING in the Main Program, that is, line 1010.

See also

MFKEY


MAX

MAX ---------- Returns the largest of two or more expressions

Type

U/BL function.

Syntax

MAX (expr, expr [,expr]...)

Arguments

expr

A numeric expression

Description

The MAX function compares its numeric arguments and returns the value of the largest of them. There must be at least two arguments.

Example

* print max(1,3,5,2,0)

5

* print max(-5,-7)

-5

* print max(-5,abs(-7))

7

See also

MIN


MCREATE

MCREATE ----------- Create a menu

Type

U/BL command and statement.

Syntax

MCREATE(mnam$,wnam$,h$,i$,d$,type[,stat])

Arguments

mnam$ | The name of the menu
wnam$ | The name of the window in which the menu is to be displayed. It must have been created.
h$ | Defines a Description Header for the Circular type menu only.
i$ | Defines the menu items, i.e. the keywords, to be displayed. The character length of each item is shown in angle brackets '<>' preceeding the item itself.
d$ | Defines the descriptions corresponding to the menu items defined by i$. This applies to the Circular and Wide Pull Down menus, where more than 50% of the description can be displayed. The length of each description is shown in angle brackets '<>' which preceed the description.
type | Specifies the menu type. It can be either: 0 for ALL Pull Down Menus, or 1 for a Circular type menu.
stat | Receives the error code.

Description

The MCREATE command creates a menu with the name specified in the mnam$ parameter, using the window described in the wnam$ parameter. The window used must first have been created by the WCREATE or WMAKE statements. The h$ parameter is used by the circular menu as a heading. The i$ parameter contains all of the itemnames preceded by their lengths. The d$ parameter contains the descriptions for the item names again preceeded by their lengths and type defines the menu type, for example, 1 for circular and 0 for both pull down types.

To use the created menu the MACTION statement must be used.

Example

In this example, the windows MENU1, MENU2 and MENU3 have all been created previously.

02500 REM CREATE MENU : CIRCULAR TYPE

02505 LET H$="Transoft Multi-Tasks/Menus/Windows/Help Demonstration"

02510 LET I$="<4>Demo<5>Menu2<5>Menu3<4>Exit"

02520 LET D$="<13>Demonstration"

02530 LET D$[0]="<21>Narrow Pull-Down Menu"

02540 LET D$[0]="<19>Wide Pull-Down Menu"

02550 MCREATE("MENUA","MENU1",H$,I$,D$,1,STAT)

02560 GOSUB 08000 : WINDOW ERROR ROUTINE

:

02600 REM CREATE MENU : NARROW PULL DOWN

02605 LET H$=""

02610 LET I$="<4>Demo<5>Menu1<5>Menu3"

02620 LET D$=""

02630 MCREATE("MENUB","MENU2",H$,I$,D$,0,STAT)

02640 GOSUB 08000 : WINDOW ERROR ROUTINE

:

02700 REM CREATE MENU : WIDE PULL DOWN

02705 LET H$=""

02710 LET I$="<4>Demo<5>Menu1<5>Menu2"

02720 LET D$="<13>Demonstration"

02730 LET D$[0]="<16>Lotus Style Menu"

02740 LET D$[0]="<21>Narrow Pull-Down Menu"

02750 MCREATE("MENUC","MENU3",H$,I$,D$,0,STAT)

02760 GOSUB 08000 : WINDOW ERROR ROUTINE

See also

BBGUIMAP

MACTION

SETGUIOPT 51

WCREATE

WMAKE


MDELETE

MDELETE ----------- Delete the specified menu

Type

U/BL command and statement.

Syntax

MDELETE(mnam$[,stat])

Arguments

mnam$ | The name of the menu.
stat | Receives the error code.

Description

Deletes the named menu.

Note: This does not delete the menu's window.

Example

:

00190 _MDELETE("MENUA",STAT)

00200 GOSUB 08000 : WINDOW ERROR ROUTINE

:


MESSAGEBOX

MESSAGEBOX ---------- Displays a Windows message box

Type

Windows Object Command

Syntax

MESSAGEBOX(TEXT$, TITLE$, MODE [, STAT])

Arguments

TEXT$ | Holds the message to be displayed
TITLE$ | Holds the title of the message box
MODE | Specifies the type of message box to display, and receives which button was pressed
STAT | Optional status return

Description

This function displays a Windows message box showing the message held in the TEXT$ string. The type of message box displayed is determined by the MODE parameter. This specifies both the set of buttons to display and any icon to include on the message box. This is achieved by combining the value specifying the button set:

Value | Description
0 | Displays a single OK button on the message box. This is the default.
1 | Displays both an OK and Cancel button
2 | Displays Abort, Retry and Ignore buttons
3 | Displays Yes, No and Cancel buttons
4 | Displays a Yes and a No button
5 | Displays a Retry and a Cancel button

with the value specifying any icon to display (the actual appearance of the icon will be dependent on the operating system that U/Gi is running on):

16 | Displays the standard Windows Stop icon
32 | Displays standard Windows Question icon
48 | Displays standard Windows Exclamation icon
64 | Displays standard Windows Information icon.

Default button properties can be set by setting the MODE parameter to:

256 | Second button is the default.
512 | Third button is the default.

To combine the required button set with the selected icon, add the two values together. For example, to display a YES/NO message box with a QUESTION icon, set MODE to be '4+64' or '68'. If you do not want to include an icon, simply set MODE to indicate the set of buttons that you wish to include.

After the message box has finished, MODE receives the value of the button pressed to acknowledge the message. This will be one of the following values:

Name | Value | Description
OK | 1 | The OK button was pressed
CANCEL | 2 | The Cancel button was pressed
ABORT | 3 | The Abort button was pressed
RETRY | 4 | The Retry button was pressed
IGNORE | 5 | The Ignore button was pressed
YES | 6 | The Yes button was pressed
NO | 7 | The No button was pressed

Note: Although message boxes are Windows objects, they do not possess an object handle. This is because they are stateless. Once a message box is displayed, no further processing will be carried out until the user has acknowledged the message (selected one of the buttons). This disables all the other Windows objects and suspends any tab order. In addition, as soon as the message box has been acknowledged, it is hidden and then destroyed. The object therefore only exists during the time when it is requiring a response from the user. This is a period when no other processing can occur. There is consequently no time when the object could be addressed via a handle, hence message boxes are created without one.

Example

The example program below generates a message box:

REM Display a message box confirming system exit

REM Set up the constants for defining/using message boxes

LET QUESTION=32 : Display a question icon on a message box

LET YESNO=4 : Display 'Yes' and 'No' buttons on a message box

LET YES=6 : The OK button was selected on a message box

LET CANCEL=2 : The CANCEL button was selected on a message box

REM Display the message box using the relevant style

LET STYLE=QUESTION+OKCANCEL

MESSAGEBOX("Do you really want to quit?","YourApplicationName",STYLE)

REM Interrogate the button used

IF STYLE=YES THEN

BYE

END IF

The program above generates the following message box:

Pressing the OK button returns you to the U/BL prompt.

See Also

BBGUIMAP

SETGUIOPT 51

STATUSMESSAGE


MFKEY

MFKEY ---------- Assign a function key to the specified menu

Type

U/BL command and statement.

Syntax

MFKEY(mnam$,fkey,rval[,stat])

Arguments

mnam$

The name of the menu

fkey

The function key value 1-34 where:

1 - 15 | Function keys 1 through 15
16 | HOME key - actioned by <SHIFT-F2> or <C1>
17 | END key - actioned by <SHIFT-F1> or <C3>
18 | PAGE UP or Up arrow to top of menu - actioned by <F1> or <C2>. Using an fkey value of 1 overrides the use of <F1> as a PAGE UP key.
19 | PAGE DOWN or Down arrow to bottom of menu - actioned by <F2> or <C4>. Using an fkey value of 2 overrides the use of <F2> as a PAGE DOWN key.
20 | HELP key.
21 | Invalid accelerator key used, that is, a key is pressed that is not the first character of a valid menu item.
22 | Undefined function key used, that is, a function key is pressed that has not been defined by the MFKEY statement.
23 | Negative motion off menu (up arrow on Lotus style menus, left arrow on drop down menus).
24 | Positive motion off menu (down arrow on Lotus style menus, right arrow on drop down menus).
25-34 | Hot-key 1-10.

rval

Returns the value when the function key is pressed

stat

Receives the error code.

Description

The MFKEY statement assigns a function key to the menu specified in the mnam$ parameter. The fkey argument contains the function key to use, and the rval argument specifies a returning value for act. This value is usually a negative value so as not to conflict with the normal act values when the menu is actioned.

The Function Keys F1 to F15 must return the normal Data General 'Dasher' values via the TDF Terminal Definition File.

If function key 21 (invalid accelerator, that is, a character is entered that is not the first letter of a menu item) is programmed, the code$ parameter in the MACTION statement will contain the invalid key that was used (but only if the invalid key returned a value that was greater than or equal to "space").

An MFKEY fkey value of 22 allows the use of any previously undefined function key. If a function key is pressed that has not been defined in a previous MFKEY statement, then the corresponding MACTION statement's act variable will contain the value specified by rval, its item variable will hold the menu item that the user was on when the key was pressed and the first byte of its code$ variable will hold the trailing character of the function key's sequence.

Using an fkey value of 22 will override an fkey of 21 (if used). It is possible to use only two MFKEY statements in a menu setup program; one for an fkey value of 21, to cater for invalid menu options, and one for an fkey value of 22 to cater for function keys.

Note: Basic depends on function keys returning the Data General function key sequences of "<30>" followed by one other character.

Examples

1. Set up function key 12 to return a value of -1.

:

00150 _MFKEY("MENUA",12,-1)

00160 _MACTION("MENUA",ACT,STAT)

00170 GOSUB 08000 : WINDOW ERROR ROUTINE

00180 IF ACT=-1 THEN GOTO 09000 : CLOSE FILES AND END

00190 ON ACT THEN GOSUB 01000,02000,03000

:

2. Set up fkey 22 so that SHIFT-F7 can be used.

:

00210 _MFKEY("MENUB",22,-99)

00220 _MACTION("MENUB",ACT,STAT,CODE$,ITEM)

00230 GOSUB 08000 : WINDOW ERROR ROUTINE

00240 IF CODE$[1,1]="g" THEN GOTO 01000

:

The user hits SHIFT-F7 ("<30>g") whilst on menu option 35. ACT will be set to -99, CODE$[1,1] is "g" (ASC(CODE$[1,1]=103) and ITEM returns 35.

See also

MACTION


MIN

MIN ---------- Returns the smallest of two or more expressions

Type

U/BL function.

Syntax

MIN (expr, expr [,expr]...)

Arguments

expr

A numeric expression

Description

The MIN function compares its numeric arguments and returns the value of the smallest of them. There must be at least two arguments.

Example

* print min(1,3,5,2,0)

0

* print min(-5,-7)

-7

* print min(-5,abs(-7))

-5

See also

MAX


MOD

MOD ---------- Returns the remainder of a division

Type

U/BL function.

Syntax

MOD (dividend,divisor)

Arguments

dividend | Any numeric expression representing the number being divided.
divisor | Any numeric expression representing the number to divide by.

Description

The MOD function divides its second argument into its first and returns the remainder. An error occurs if the divisor is zero (see last example below).

Example

* print mod(7,3)

1

*list

00010 INPUT X,Y

00020 PRINT MOD(X,Y)

00030 GOTO 00010

* run

? 12,3

0

? 10,4

2

? 1,0

Error 16 - Arithmetic at line 20


$N

$N ----------- Step through a specified number of lines of code

Type

U/BL command.

Syntax

$N [arg]

Arguments

arg

A numeric expression specifying the number of lines to step through.

Description

After setting a break point with the $B command, and RUNning a program, you can step through lines of code with the $N command.

A numeric argument after $N indicates the number of lines to step through, defaulting to 1 if there is no argument.

The line which is about to be executed is displayed after typing $N.

See also

$B

$T

STEP


$NUMERIC

$NUMERIC ---------- Adjusts for the precision of each component

Type

U/BL Command and Statement.

Syntax

$NUMERIC var1(n.m){,var2(n.m)...}

Arguments

var1(n.m)

A numeric variable, where:

n - is the number of integer digits, and

m - is the number of implied decimal places.

Description

An arithmetic expression using $NUMERIC variables, adjusts for the precision of each component.

Examples

00010 $NUMERIC TAX(4.2),PRICE(10.3)

Assignment to a $NUMERIC variable will "scale" automatically:

00020 LET TAX=15

will store "1500" in the variable TAX. Decimal constants can also be used:

00020 LET TAX=15.00

PRINTing $NUMERIC variables outputs the integer value:

* print tax

1500

Assignment to an integer also transfers the integer amount:

* x=tax

* print x

1500

however,

* x=tax + 0

* print x

15

This is because the $NUMERIC variable TAX is used in an expression.

*list

00010 REM $NUMERIC FUEL_COST(10.2),DISTANCE(10.0),MPG(10.4),COST_PG(10.2)

00020 LET DISTANCE=1234 \ MPG=17.1234 \ COST_PG=0.75

00030 LET FUEL_COST=(DISTANCE/MPG)*COST_PG

00040 LET POUNDS=INT(FUEL_COST)

00050 LET PENCE=100.0*(FUEL_COST-POUNDS)

00060 PRINT "Fuel Cost is:";FUEL_COST

00070 PRINT "Consists of";POUNDS;" Pounds"

00080 PRINT " and";PENCE;" pence"

* run

Fuel Cost is:54.05

Consists of 54 Pounds and 5 pence

See also

BBFVAL


NEW

NEW ---------- Clears the current level of working storage

Type

U/BL Statement and Command.

Syntax

NEW

Description

The NEW command clears currently loaded statements and variables from working storage at the current SWAP level, CLOSES any open files, and removes any file locks. If the SWAP level is not zero, the NEW command moves up one SWAP level.

Example

* list

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

* new

* list

Line number


NEXT

NEXT ---------- Ends a FOR loop and updates the counter variable

Type

U/BL statement.

Syntax

NEXT counter

Arguments

counter

The numeric variable which was specified as the loop control variable by the matching FOR statement.

Description

The NEXT statement adds the STEP value from the corresponding FOR statement to the counter variable (or 1 if no STEP was specified) and returns control to the FOR statement where the value of the counter is used to decide whether the loop should continue.

For compatibility with B32 Business Basic, U/BL supports up to 20 levels of nested FOR/NEXT loops. Note that this functionality is part of the core product. The BBEXTENSION environment variable does not have to be set to include B32 in order to use it.

Example

See the example provided under the FOR statement.

See also

FOR

STMA 8


NOCONTROL

NOCONTROL ---------- RESETs to 0 the terminal control flag for discarding control characters

Type

U/BL Statement.

Syntax

NOCONTROL

Description

The NOCONTROL statement SETS the value of the CONTROL flag to 0. This causes control characters to be discarded.

It is equivalent to the STMA 7,2 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See STMA 5 & 6 & 7.


NOFILLC

NOFILLC ---------- RESETs to 0 the terminal control flag for fill characters

Type

U/BL Statement.

Syntax

NOFILLC

Description

The NOFILLC statement SETS the value of the FILL flag to 0. When this flag is set to 0, PRINT USING type D or E field mask characters to the left of the first significant digit are not replaced by fill characters.

The default fill character (blank) always replaces mask characters to the left of the first significant digit, even if SETFILLC (STMA 6,7) is in effect.

Note: SWAP saves this value, and unSWAP restores it. If the swapped-to program changes this value, it is restored to its prior value when the swapped-to program ENDs.

If the fill character is blank, the mask characters are always overwritten, even if NOFILLC is in effect.

The NOFILLC statement is equivalent to the STMA 7,7 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See STMA 5 & 6 & 7.


NOT

NOT ---------- Reverses the Boolean value of any expression

Type

U/BL operator

Syntax

NOT expr

Arguments

expr

Any boolean or numeric expression.

Description

The NOT operator reverses the Boolean value of any expression. The expression is first evaluated resulting in either a number or a TRUE or FALSE value. If it results in a number, and the number is zero, or it results in a FALSE value, the NOT operator returns TRUE.

Example

* list

0010 IF NOT (5>6) THEN PRINT "Just as well" ELSE PRINT "Something fishy here"

0020 IF NOT (SYS(24)) THEN PRINT "Not at zero swap level" ELSE PRINT "At zero swap level"

* run

Just as well

At zero swap level

See also

AND

OR


NOTIKEY

NOTIKEY ---------- SETs the terminal control flag that controls processing if the IKEY interrupts

Type

U/BL Statement.

Syntax

NOTIKEY

Description

The NOTIKEY statement SETS the value of the IKEY to 1. When the flag is set to 1, IKEY is not processed until the flag is RESET to 0. This allows you to disable interrupts until they can be properly processed. If there are any pending IKEY interrupts, the SYS(26) statement yields a value of 1. This flag and the pending interrupt can be cleared with the RESETIKEY (STMA 8,3) statement.

The NOTIKEY statement is equivalent to the STMA 6,5 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


@OFFSET

@OFFSET ---------- Set the current 'y' coordinate (line) offset

Type

U/BL statement.

Syntax

@OFFSET offset

Arguments

offset

A numeric expression that specifies the current offset to a field's 'y' coordinate (line).

Description

The @OFFSET statement sets an offset that is used whenever a @PRINT or @INPUT statement positions the cursor to a field. The offset is added to the line specification ('y' coordinate) in the field specs. For example, if @OFFSET 10 was executed, and a filed's 'y' coordinate specified in the @SETSD was 3, then the field would actually display on line 13.

This statement allows file inquiries for information from more than one record to be displayed. This is useful when developing parameter driven software.

Whenever a program starts this value is zero.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


ON ERR

ON ERR ---------- Enables or disables error handling

Type

U/BL statement.

Syntax

Format 1: ON ERR THEN statement

Format 2: ON ERR THEN INT

Arguments

statement

Any U/BL statement except the following:

  • ATA

  • DEF FN

  • $DO_WHILE/$END_DO

  • END

  • FOR/NEXT

  • IF

  • REM.

Description

The ON ERR statement allows most errors occurring during a program to be controlled by the programmer. If no ON ERR statement is active, and an error occurs, U/BL prints an error message and stops the program. If an ON ERR statement has been encountered, and an error occurs, the statement following the ON ERR statement executes. The ON ERR THEN INT statement turns off error trapping.

Some statements, such as OPEN FILE, trap any error themselves. If the error trap in such statements is used, any ON ERR trap is not executed. The $DEBUG's $E command can be used to toggle the ON ERR trap on and off.

Examples

1. A global error handling subroutine.

00010 ON ERR THEN GOSUB 01000 : Error handling subroutine

00020 REM Normal program statements

......

......

00990 END

01000 REM Error handling subroutine

01010 LET ERROR=SYS(7) : GET ERROR NUMBER

01020 DIM ERRMESS$[64]

01030 LET ERRMESS$=ERM$(ERROR) : GET ERROR MESSAGE

01040 PRINT "Error in program - no ";ERROR;" - ";ERRMESS$

01050 STOP

2. Trapping any errors in a specific statement.

00500 REM Accept integer in Z, with prompt in PROMPT$

00510 ON ERR THEN GOTO 00520

00520 PRINT

00530 PRINT PROMPT$;

00535 REM Numeric input only - alpha will be trapped

00540 INPUT USING "","",Z 00550 ON ERR THEN INT

00560 RETURN

See also

$DEBUG

ON IKEY


ON GOSUB

ON GOSUB ---------- Branches to one of several lines, depending on the value of an expression

Type

U/BL statement.

Syntax

ON expr [THEN] GOSUB line_no[,line_no]...

Arguments

expr | Any numeric expression.
line_no | Any valid line number in the program.

Description

The expression specified in the expr parameter is evaluated. If the result is 1, a GOSUB is executed to the first line number specified by the line_no parameter. If the result is 2 or greater, a GOSUB is executed to the corresponding line number. If the result is zero or less, or greater than the number of line numbers specified, the next statement following the ON GOSUB statement is executed.

Example

* list

00005 GOSUB 00200 : Initialisation

00010 PRINT "MAIN MENU"

00020 PRINT

00030 PRINT "1 View a customer 2 Add a customer"

00050 PRINT "3 Change a customer 4 Delete a customer"

00070 PRINT "5 Reports menu 6 End"

00090 PRINT

00100 INPUT USING "","Enter your choice...",CHOICE

00110 ON CHOICE GOSUB 01000,02000,03000,04000,05000,06000

00120 GOTO 00010

00200 REM Initialization

...

00990 RETURN

01000 REM View a customer

...

01990 RETURN

...

02000 REM Add a customer

...

...

See also

GOSUB

ON GOTO

REM

RETURN


ON IKEY

ON IKEY ---------- Enables or disables interrupt trapping

Type

U/BL statement.

Syntax

Format 1: ON IKEY THEN statement

Format 2: ON IKEY THEN INT

Arguments

statement

Any U/BL statement except the following:

  • DATA

  • DEF FN

  • $DO_WHILE/$END_DO

  • END

  • FOR/NEXT

  • IF

  • REM.

Description

The ON IKEY statement allows program interrupts to be controlled by a programmer. Program interrupts occur when a user presses the <Esc> key or a key defined as the interrupt key using the STMA 4,6 or STMA 4,7 statements. The interrupt key can also be defined using the esc function in the Terminal definition file (tdf).

If no ON IKEY statement is active, and an interrupt occurs, U/BL stops executing the current program with the message "IKEY at nnnnn", where nnnnn is the U/BL program line being executed when the KEY was pressed. If an ON IKEY statement has been encountered, and an interrupt occurs, U/BL executes the statement specified after the THEN in the ON IKEY THEN statement.

The ON IKEY THEN INT statement means that U/BL will stop executing the current program with the message "IKEY at nnnnn", where nnnnn is the U/BL program line being executed when the IKEY was pressed.

You can also use the STMA 6,5 statement to disable interrupt trapping, and re-enable it using STMA 7,5. The ON IKEY trap can be toggled on and off with $DEBUG's $I command. While disabled, a program can test whether an interrupt occured by testing SYS(26).

Example

* list

00005 DIM PASSWORD$[10]

00007 REM Trap any interrupt

00010 ON IKEY THEN GOTO 00120

00020 PRINT "Enter Password: ";

00030 STMA 6,8 : NO ECHO

00040 INPUT PASSWORD$

00045 REM Enable echo again

00050 STMA 7,8

00060 IF PASSWORD$="transoft" THEN

00070 PRINT "Welcome, user"

00080 ELSE

00090 PRINT "Password incorrect!"

00100 END IF

00110 END

00115 REM We wouldn't want to leave echo turned off

00120 STMA 7,8

00130 PRINT "A valid password must be entered"

See also

INTERRUPT


ON...GOTO

ON...GOTO ---------- Branches to one of several lines depending on the value of an expression

Type

U/BL statement

Syntax

ON expr [THEN] [GOTO] line_no[,line_no]...

Arguments

expr | Any numeric expression.
line_no | Any valid line number in the program.

Description

The expression specified in the expr parameter is evaluated. If the result is 1, a GOTO is executed to the first line number specified in the line_no parameter. If the result is 2 or greater, a GOTO is executed to the corresponding line number. If the result is zero or less, or greater than the number of line numbers specified, the next statement following the ON GOTO statement is executed.

Example

* list

00010 PRINT "MAIN MENU"

00020 PRINT

00030 PRINT "1 - View a customer"

00040 PRINT "2 - Add new customer"

00050 PRINT "3 - Delete a customer"

00060 PRINT "4 - End"

00070 PRINT

00080 INPUT USING "","Enter your choice...",CHOICE

00090 ON CHOICE THEN GOTO 00100,00200,00300,00400

00100 REM View customer details

......

00200 REM Add new customer

......

00300 REM Delete customer

......

00400 REM quit

00410 END

See also

GOTO

ON GOSUB


OPEN

OPEN ---------- Enables Input/Output to a file or device

Type

U/BL command and statement.

Syntax

OPEN {errcode,}FILE[chan, mode],filename

Arguments

errcode | A numeric variable which receives an error code if the OPEN is not successful.
chan | A numeric expression representing the channel, which is used to refer to the file subsequently. Channel numbers range from 0 to whatever the environment variable BBCHAN has been set to. Channel 16 is reserved for the screen/keyboard.
mode | A numeric expression which determines the access method to be used with the file.
filename | A valid filename, optionally including a pathname.

Description

A file must be OPENed before any I/O operation can be performed on it. The OPEN command assigns a channel to the file and determines the mode of access to be used with the buffer. If the optional error code varaiable errcode is used, in the OPEN statement, any error which occurs when the file is opened, causes an error code to be placed in this variable. An ON ERR statement will not be executed if the error code variable errcode is specified.

The Data General Business BASIC modes are numbered 0 to 6. Mode 7 has no fast equivalent, mode 8 is a new mode.

Mode 0 | OPENs a random disk file in exclusive mode, allowing both input and output, and creating it if it cannot be found in the current directory or a directory in the search list.
Mode 1 | OPENs a sequential disk file or device for exclusive output, deleting any existing file. Only the current directory is searched for the file. Only WRITE FILE and PRINT FILE statements can be used in this mode. If the environment variable BBEXTENSION is set to include B32, the POSITION FILE statement can be used on files OPENed in this mode.
Mode 2 | OPENs a sequential disk file or device for exclusive output, positioning at the end of any existing file (append mode) or creating a new one. The current directory and then the searchlist is used to attempt to find the file.
Mode 3 | OPENs a device or file for shared input. The file must exist in the current directory or a directory on the searchlist. READ FILE, INPUT FILE and POSITION FILE statements are allowed. Many users can OPEN a file in this mode at one time.
Mode 4 | OPENs a disk file (not a device) for shared input. The file must exist in the current directory or a directory on the searchlist.
Mode 5 | OPENs a random disk file in shared mode, allowing both input and output. The file must exist in the current directory or a directory on the searchlist. Since many users can access the same file in this mode, LOCKing should be used when updating the file.
Mode 6 | OPENs a random disk file for exclusive use, allowing both input and output. The file must exist in the current directory or a directory on the searchlist. Mode 6 is transformed into mode 18 (which uses the LRU chain) when the MODE_18 switch is turned on, or into mode 16 (which doesn't use the LRU chain) when MODE_18 is turned off but BLOCK_IO is.
Mode 7 | OPENs a tape or cassette device. The only I/O statement which can be used with mode 7 is MTDIO.
Mode 8 | OPENs a file or device in binary mode. This mode is useful for OPENing devices from which you want to be able to read control character sequences such as ^S, for example, a time clock. If OPENing a printer and the environment variable BBSPOOL isn't set, set the environment variable BBRESOLVE to Y.

Examples

  1. The following statement OPENs a file for exclusive random access, creating it if needed. The file is OPENed in the slow mode. If the file cannot be OPENed, for example, because another user already has exclusive use of it, an error is generated:

    00010 OPEN FILE[0,0],"MYFILE"

  2. The following program segment prompts for a filename and creates a file for sequential output, first deleting the file if it already exists.

    00010 DIM FILENAME$[60] 00020 INPUT "Enter name of log file...",FILENAME$

    00030 OPEN FILE[1,1],FILENAME$

    00040 PRINT FILE[1],"Beginning log at";SYS(14);":";SYS(13);":";SYS(12)

  3. The next program reads a sequential file and displays its contents on the screen. The file name is prompted for, and error trapping is used.

    00010 DIM FILENAME$[60],RECORD$[80]

    00020 INPUT "Enter name of a text file...",FILENAME$

    00030 IF LEN(FILENAME$)=0 THEN END

    00040 OPEN ERROR,FILE[0,3],FILENAME$

    00050 IF ERROR THEN

    00060 PRINT "Sorry, can't open that file - try again"

    00070 GOTO 00020

    00080 END IF

    00090 INPUT FILE[0],USING "",RECORD$

    00100 IF EOF(0) THEN GOTO 00130

    00110 PRINT RECORD$

    00120 GOTO 00090

    00130 CLOSE FILE[0]

    00999 END

See also

CLOSE


OR

OR ---------- Returns the result of a logical OR of its arguments

Type

U/BL operator

Syntax

OR(expr, expr [,expr]...)

Arguments

expr

Any boolean or numeric expression

Description

The OR function compares its numeric arguments a bit at a time. If at least one argument has the bit is set on, it sets the corresponding bit of its return value. If the bit on all its arguments is clear, OR clears the corresponding bit of its return value. Usually, OR is used to set bits in a number. One argument is the number, and the other is a power of two corresponding to the bit to set.

Example

The following program uses the OR function to OR a number with 2:

00005 DIM X$[20]

00010 INPUT "Enter a number...",X

00020 LET X$="OR(",X,",2)=",OR(X,2)

00030 PRINT X$

* run

Enter a number...12

OR(12,2)=14

* run

Enter a number...11

OR(11,2)=11

The two examples above work like this:

00001100 (12 decimal) 00001011(11 decimal)

00000010 ( 2 decimal) 00000010( 2 decimal)

--------              --------

00001110 (14 decimal) 00001011(11 decimal)

See also

$XOR

AND


OR

OR ---------- Performs a Boolean OR of two expressions

Type

U/BL operator

Syntax

OR expr

Arguments

expr

Any boolean or numeric expression

Description

The OR operator ties together two expressions, and returns a value of TRUE if either of the expressions evaluates to TRUE. If neither expression is TRUE, OR returns FALSE. A numeric expression is considered TRUE if it evaluates to non-zero. There is no need for expressions tied together with OR to be of the same type.

Example

The following program fragment demonstrates the use of the OR operator:

1100 REM If offered voluntary redundancy

1110 IF JOBS_STATUS$="Easy to get" OR (AGE>60 AND PENSION_FUND>100000) THEN

1120 PRINT "Take the money and run"

1130 ELSE

1140 PRINT "Hang in there"

1150 END IF

See also

$XOR

AND

NOT


@PACK

@PACK ------------ Build a record string

Type

U/BL Statement.

Syntax

@PACK first_field,record,list

Arguments

first_field | A numeric expression that specifies the first field to move into the record string.
record | A string variable into which all the fields from the list are moved.
list | A list of string variables, string literals, or numeric expressions to be moved to the record string.

Description

The @PACK statement moves the information specified in the list argument into the record string even if the field type is different from the field being moved. For example, if the first field's definition is a six-byte alpha field but it is a numeric expression, 6 bytes are moved from the current stack location. The length of the fields and the location to where they are moved is specified in the field specs which are defined by the @SET statements.

The error #ERR=84 occurs if a field references a byte in the record string beyond the current length. A filed cannot be moved into the record string beyond the current length. The same error also occurs if the field to be moved into the record string has a current length less than the number of bytes as described by the field definition.

The field definition is not used if bit 3 of the byte flags is set. Therefore if field 2 had bit 3 set, then @PACK 1,REC$,X,Y$,Z*2 uses field definition 1 for X, field definition 3 for Y$, and field definition 4 for Z*2.

This statement is similar to the PACK statement. Use the PACK statement instead of the @PACK statement in most cases, as it is more flexible and has field type error checking.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


@PRINT

@PRINT ------------ Display screen-formatted information from a record

Type

U/BL Statement.

Syntax

@PRINT first_field,number,record

Arguments

first_field | A numeric expression specifying the first field number to display.
number | A numeric expression specifying the number of fields to display.
record | A string variable containing the information to display.

Description

The @PRINT statement provides a method for formatting and displaying any number of fields from a record. Each of the fields used by the @PRINT statement must have previously defined by the @SET statement. The field definition includes:

  • The location on the screen where the field is displayed and input

  • The position in the record where the field information is located

  • The type of the field

  • The length of the field

  • The number of decimals in the field

  • Special editing flags.

When a type O field is displayed, the option table associated with a field is searched for the value in the record. If there is a match, the table's corresponding display value is shown. If there is no match, then the value in the first table entry is displayed.

The @PRINT statement displays the specified number of fields starting at the specified first field. The information for all the fields is assumed to be in the referenced record string. For numeric, Julian or crammed fields the statement the information is converted into ASCII and displayed on the terminal at the line and column specified in the @SET or @SETSD statement.

An run-tme error #ERR=83, occurs if the field specs set by the @SET statements reference a byte less than 1 or greater than the dimension of the record string. An run-tme error #ERR=86, occurs if the @PRINT statement tries to display a field which has not been defined by a @SET or @SETSD statement.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


@PUTFLD

@PUTFLD ---------- Move a key into a record string

Type

U/BL Statement.

Syntax

@PUTFLD first_field,number,record,key_field

Arguments

first_field | A numeric expression specifying the first field to move.
number | A numeric expression specifying the number of fields to move.
record | A string variable into which the field information is moved.
key_field | A string variable which contains the information to be moved. Each of the fields are assumed to be in contiguous locations.

Description

The @PUTFLD statement is the inverse of the @GETFLD statement. It is used to move a key into a record string. The @PUTFLD statement extracts the specified number of fields from the key field and moves them to the record string starting with the specified first field number.

The location of the fields in the record string are determined by the field specs defined by the @SET statements. The first field is extracted from the key field located at the first byte of the variable. The remaining fields are extracted from the key field at the next contiguous locations.

The current length of the record string must be as least as large as the highest numbered byte moved or a run time error (#ERR=84) occurs. For example, if a field is defined as 4 bytes starting at byte 87, then the current length of the record string must be at least 90. The current length of the key field string must be at least as large as the number of bytes or a run time error (#ERR=83) occurs.

The main purpose of this statement is to update an index file key in a record when the key is comprised of multiple, non-consecutive fields.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

Assuming that fields 2-5 comprised bytes 1-6,9-10,7-8, & 20-26, then the single statement listed below is the same as the four statements listed after it:

@PUTFIELD 2,4, REC$,KEY$

REC$(1,6)=KEY$(1,6)

REC$(9,10)=KEY$(7,8)

REC$(7,8)=KEY$(9,10)

REC$(20,26)=KEY$(11,17)


$P

$P ------------ Display a dump of the U/BL program details

Type

U/BL command.

Syntax

$P

Description

The $P command displays to screen, a detail dump of the U/BL program details, such as the last error, the environment variables currently in use, the FOR/NEXT stack, the GOSUB/RETURN stack, contents of variables and the 'size' of the program etc.

On the UNIX platform, $P displays all of the environment variables defined in BBENV, together with any UNIX environment variables which start with the letters "BB". Only those lines in the BBENV file which begin with a letter, number or underscore and which contain an "=" sign will be referenced. When the screen scrolls, the "MORE (Y/N)?" prompt will accept Y to continue the display and N or Q to finish.

Use the $D command to dump the display to a disk file.

Example

  UBL Debug Report - Mon Dec 22 14:04:24 1999

UBL Build date 22-Dec-99

UBL Environment Variables:

BBSIGNON=\USER\UBL\YOURBAN.BAN

BBTERM=\USER\UBL\COLOR.TDF

BBSOURCE=\USER\BBSOURCE

BBPROGS=\USER\BBPROGS

BBROOT=\USER\DATA

BBLINK=\USER\DATA\LINKS

BBERM=\USER\UBL\BASIC.ER

BBTMP=\TMP

BBSWAP=\TMP\SWAP

BBSPOOL=\USER\UBL\SPOOL.BAT

BBDEBUG=Y

Current Directory: \USER\DATA

Program: TESTPROG

Line No: 01000

On IKEY: Not defined

On ERROR: Not defined

Last Error: ERROR -10 - File Not Found: NEWFILE at line 01000

FOR/NEXT stack:

Index var: C Begins @ 00050 Step: 4 Value: 4

Index var: B Begins @ 00030 Step: 5 Value: 2

Index var: A Begins @ 00020 Step: 1 Value: 1

GOSUB/RETURN stack: 00060 00110

Open Channels:

Chan Mode Gpos Name................

0 5 512 :FILE1

1 5 124 :FILE2

Numeric Variables:

A LN% 6

B 2 PTR 0

C 4

CHAIN% 3

Strings:

X1$ 255 256 X2$ 0 0 X3$ 0 0

REC$ 0 0

String Content:

X1$

1 0102 0304 0506 0708 090a 0b0c 0d0e 0f10 ................

17 1112 1314 1516 1718 191a 1b1c 1d1e 1f20 ................

33 2122 2324 2526 2728 292a 2b2c 2d2e 2f30 !"#$%&'()*+,-./0

49 3132 3334 3536 3738 393a 3b3c 3d3e 3f40 123456789:;<=>?@

65 4142 4344 4546 4748 494a 4b4c 4d4e 4f50 ABCDEFGHIJKLMNOP

81 5152 5354 5556 5758 595a 5b5c 5d5e 5f60 QRSTUVWXYZ[\]^_`

97 6162 6364 6566 6768 696a 6b6c 6d6e 6f70 abcdefghijklmnop

113 7172 7374 7576 7778 797a 7b7c 7d7e 7f80 qrstuvwxyz{}~..

129 8182 8384 8586 8788 898a 8b8c 8d8e 8f90 ................

145 9192 9394 9596 9798 999a 9b9c 9d9e 9fa0 ................

161 a1a2 a3a4 a5a6 a7a8 a9aa abac adae afb0 ................

177 b1b2 b3b4 b5b6 b7b8 b9ba bbbc bdbe bfc0 ................

193 c1c2 c3c4 c5c6 c7c8 c9ca cbcc cdce cfd0 ................

209 d1d2 d3d4 d5d6 d7d8 d9da dbdc ddde dfe0 ................

225 e1e2 e3e4 e5e6 e7e8 e9ea ebec edee eff0 ................

241 f1f2 f3f4 f5f6 f7f8 f9fa fbfc fdfe ff ...............

Program Size:

Press any key for size display.

See also

$D

SIZE


$PUTENV

$PUTENV ---------- Add a new or replace an existing environment

Type

U/BL Statement or Command.

Syntax

$PUTENV env$,val$[,err]

Arguments

env$ | A string expression specifying the environment variable to be changed.
val$ | A string variable giving the new value for the environment variable.
err | A numeric variable that will be 0 if the change worked or -1 if there is not enough environment memory available for the change to take place.

Description

The $PUTENV command replaces the value associated with an environment variable, or adds a new environment variable.

Not all environment variables can be changed by $PUTENV. See the entry for the individual environment variable for further details.

Note: You cannot change operating system environment variables with $PUTENV.

Example

01000 LET P$="/user/progs:/user/lib"

01010 REM $PUTENV "BBPROGS",P$,ER

See also

$GETENV


PACK

PACK ------ Moves elements into a string

Type

U/BL command and statement.

Syntax

PACK rform$, record$ [,element]...

PACK line_no, record$ [,element]...

Arguments

rform$ | A string expression representing the format of record$.
record$ | A dimensioned string or substring which has the elements moved into it.
element | An expression to be moved into the string. Strings and numeric expressions can be mixed, but they must correspond to the string format.
line_no | The line number of an RFORM statement corresponding to the format of record$.

Description

The PACK command is used to move the contents of a number of variables or literals into a string, for example, when preparing a record for output.

The record$ argument being packed must be filled to an appropriate length before the PACK statement is executed, unless the RFORM statement begins with a Z statement, which null fills the string.

Example

The following program segments set up a record for a database containing people's names, heights and shoe sizes.

00010 DIM RECORD$[23],NAME$[20],FORM$[10]

00020 RFORM ZA20CB

00030 REM The above statement specifies the record is to be

00040 REM null filled (Z). The first 20 bytes will be a

00050 REM 20 byte truncated string, the next 2 bytes will

00060 REM be an unsigned integer (C), & the last byte will

00065 REM be an unsigned integer (B) ....

00190 REM Assuming that our variables are set with the desired values

00200 PACK 00020,RECORD$,NAME$,HEIGHT,SHOE_SIZE

00210 REM Now we can write the record to a file

 ....

00390 REM The next line does exactly the same thing as line 00200

00400 PACK "ZA20CB",RECORD$,NAME$,HEIGHT,SHOE_SIZE

 ....

00590 REM the next two statements do exactly the same thing again

00600 LET FORM$="ZA20CB"

00610 PACK FORM$,RECORD$,NAME$,HEIGHT,SHOE_SIZE

See also

RFORM

UNPACK


POS

POS ---------- Returns the position of the first occurrence of a string in another string

Type

U/BL function.

Syntax

POS (long$,short$,start_pos)

Arguments

long$ | A string expression within which the string specified in the short$ parameter may occur.
short$ | A string expression which the POS function attempts to find in the long$ string.
start_pos | The first byte at which the POS function begins searching the long$ parameter. If start_pos is less than zero, then an error occurs.

Description

The POS function searches for short$ in the long$. The search is started at the byte position specified in the start_pos parameter. If start_pos is greater than the length of long$, or short$ cannot be found in long$, the POS function returns a value of zero. If short$ is found, then the POS function returns the byte at which short$ begins in long$.

Example

* list

00010 DIM X$[100],Y$[10]

00020 INPUT USING "", "Enter a long string ",X$

00030 INPUT USING "","Enter a shorter string ",Y$

00040 START=POS(X$,Y$,1)

00050 IF START=0 THEN GOTO 00100

00060 PRINT Y$;" found at";START

00070 START=POS(X$,Y$,START+1)

00080 GOTO 00050

00100 END

* run

Enter a long string THE RED FOX JUMPED OVER THE LAZY DOG

Enter a shorter string THE

THE found at 1

THE found at 25

See also

SCANUNTIL

SCANWHILE

STRPOS


POSITION FILE

POSITION FILE ---------- Moves the file pointer to a particular byte in a file

Type

U/BL command and statement.

Syntax

POSITION FILE (channel, byte)

Arguments

channel | A numeric expression representing the channel used to OPEN the file.
byte | A numeric expression for the byte at which to position. Files start at byte 0. If byte is -1, U/BL positions to the end of the file.

Description

The POSITION FILE command moves the file pointer to a specific byte in an open file. Any subsequent I/O statements begin at that point. The byte position of a record in a file of fixed length records, can be calculated by multiplying the record size by the record number.

The POSITION FILE command can only be used on sequential files (that is, those OPENed in mode 1) if the environment variable BBEXTENSION is set to include B32.

Example

Example program to retrieve specific records:

* list

00010 DIM REC$[298]

00020 LET RECSIZE=298

00025 OPEN FILE[0,15],"DATAFILE"

00030 INPUT "Enter the number of the record to retrieve...",RECNUM

00040 POSITION FILE[0,RECSIZE*RECNUM]

00050 READ FILE[0],REC$

00060 PRINT REC$

00070 GOTO 00030


PREVPROG

PREVPROG ---------- Returns the name of the program which SWAPped to the current one

Type

U/BL command and statement

Syntax

PREVPROG str$

Arguments

str$

A string variable which receives the name of the calling program.

Description

The PREVPROG statement returns the name of the program which SWAPped to the current one.

The upper case version of the program name is returned in the str$ parameter. If the program was not SWAPped to, then PREVPROG returns a zero length string.

Example

PROGA is as follows:

00010 PRINT "In PROGA Now"

00020 SWAP "PROGB"

and PROGB is

00010 DIM PPROG$[20]

00020 PRINT "Now In PROGB"

00030 PREVPROG PPROG$

00040 PRINT "Previous Program was: ";PPROG$

* run "proga

In PROGA Now

Now In PROGB

Previous Program was: PROGA


PRINT

PRINT ---------- Outputs data on the screen

Type

U/BL command and statement.

Syntax

PRINT [delim] [expr] [delim expr]... [delim]

; [delim] [expr] [delim expr]... [delim]

Arguments

delim | Either a comma or semi-colon can be used as a delimiter between expressions. If the BBTABWIDTH environment variable is not zero, a comma produces a tab, while a semi-colon makes the next expression print immediately after the current one. If BBTABWIDTH isn't set, or if it is set to zero, a comma will be treated as a semi-colon. A delimiter at the end of the line applies to the next PRINT statement.
expr | Any expression, including numeric or string variables or literals, a TAB expression, or any terminal or cursor control expression.

Description

The PRINT command displays literals and the contents of variables on the screen. If no terminal or cursor control functions are used, the PRINT command displays its data at the current position on the screen. The PRINT command without any arguments simply prints a blank line. If the PRINT statement ends with a delimiter, the next statement which produces output to the terminal stays on the same line. Without a final delimiter, the PRINT command generates a new-line character after the last expression.

The PRINT command will print up to the number of characters specified by the BBLINE environment variable or the STMA 4,8 statement. The default is 132, but the column counter can be disabled with the STMA 6,3 statement. A maximum of 132 characters can be output by a single PRINT statement, unless LINE_LEN has been changed, using the $SET_VALUE statement or the BBLINE environment variable.

The TAB expression may be used for spacing of expressions within a PRINT statement.

Positive numbers are PRINTed with a leading and trailing space, and negative numbers have a leading minus sign and a trailing space. Strings must contain text characters only, and are only displayed up to the first null, form feed or end-of-line character. To display a string containing special characters, use the WRITE statement.

@ expressions

Special expressions can be included to position the cursor and alter the characteristics of the terminal. These expressions all begin with an @ sign, and consist of one or two numbers in brackets. They should normally be followed by a semi-colon, as a comma will move the current position. If long PRINT statements contain @ expressions, the extra characters generated for terminal and cursor control may cause the statement to exceed the page width. In this case, disabling the column counter with the STMA 6,3 statement may be necessary.

There are three distinct classes of @ expression:

@(line[,column]) | Cursor Positioning. Line and column are both positive numbers.
@(item,value) | Terminal Characteristic. Item is a negative number and value is either an ASCII value or status flag number. See Appendix F.
@(item) | Terminal Control. Item is a negative number. See Appendix G.

Setting the BBLIMITNROW environment variable to Y forces any PRINT @(ROW,COL) commands with a ROW that is greater than the number of rows on the screen to go to the last line of the screen. This was implemented to maintain compatibility with DG terminals. If this environment variable is not set and you use a PRINT @(ROW,COL) command with a ROW that is greater than the number of rows on the screen, then the results are unpredictable, depending on which terminal you are using.

Examples

1. Some simple print statements.

* dim x$[10]

* x$="Hello" \ a=42 \ b=-63

* print "This is a test";a;b;X$

This is a test 42 -63 Hello

* ; "This is a test",a,b,X$

This is a test 42 -63 Hello

* 10 print "This is one line"

* 20 print "This ";

* 30 print "is another"

* run

This is one line

This is another

2. Using the TAB expression.

* print "Hello";TAB(40);"world"

Hello      world

3. Using direct cursor positioning.

* 10 for I = 1 TO 3

* 20 ;@(I,I*5);I

* 30 next i

* run

1

2

3

See also

BBLIMITROW

BBLINE

BBTABWIDTH

PRINT USING

Terminal Characteristics

Terminal Control Characters

TDF Keywords.


PRINT FILE

PRINT FILE ---------- Writes data to a sequential file

Type

U/BL command and statement.

Syntax

PRINT FILE (channel), [delim] [expr] [delim expr]..[delim]

; FILE (channel), [delim] [expr] [delim expr]... [delim]

Arguments

channel | The channel number used to OPEN the file.
delim | Either a comma or semi-colon. If the BBTABWIDTH environment variable is set, then a comma produces a tab, while a semi-colon makes the next expression print immediately after the current one. If BBTABWIDTH is not set, a comma will be treated as a semi-colon.
expr | Any expression, including numeric or string variables or literals, a TAB expression, or any terminal or cursor control expression.

Description

The PRINT FILE command writes data-sensitive output to a text file in a format suitable for an INPUT FILE command to read. If the PRINT FILE command is used to print several statements at once, and the INPUT FILE command is to be used to read the file, a comma should be printed between each of the statements. For binary output to a file, use the WRITE FILE statement instead of PRINT FILE.

In general, the PRINT FILE command is similar to the PRINT command, but trailing delimiters and most @ expressions are ignored, with the exception of @(-30), which produces a form feed character to throw a page in a print file. The PRINT FILE[16] statement is a special case, and behaves as a PRINT statement, outputting its data to the console.

Example

Simple program which allows you to enter some data from the keyboard, and then writes the data to the file 'NOTEFILE'.

* list

00010 DIM X$[80]

00020 OPEN FILE[0,11],"NOTEFILE"

00030 PRINT "Type some notes. A blank line finishes."

00040 INPUT USING "","",X$

00050 IF X$<>"" THEN PRINT FILE[0],X$ ELSE GOTO 00070

00060 GOTO 00040

00070 CLOSE FILE[0]

00080 END

See also

INPUT FILE

WRITE FILE


PRINT USING

PRINT USING ---------- Outputs formatted data to the screen

Syntax

PRINT USING format, expression [,expression]...
; USING format, expression [,expression]

Arguments

format | A string literal or variable consisting of special formatting characters used to determine the field and format of the following expressions
expression | Any expression, including numeric or string variables or literals

Description

The PRINT USING statement displays data on the screen using a format determined by the format string. A buffer of 132 bytes holds the formatted text.

The format string can hold a mixture of codes and string literals in any order, separated by commas. String literals must be enclosed in single quotes. Any format code can be repeated a number of times by enclosing it in brackets and preceding it with a number. Format codes may be in upper or lower case, although the statement executes slightly more quickly of you use uppercase format codes.

If more expressions are supplied than the format codes allow for, the program repeats application of the format string as necessary. If fewer expressions are supplied, the unused portion of the format string is ignored.

The following are the permitted format codes:

Format code

Meaning

An

Outputs n characters from a string. If the string is shorter than n, spaces are appended to make up the length. Any null characters are replaced by spaces.

Dw[.d]

Outputs a number using a total of w columns and placing d digits to the right of the decimal point. If d is not specified, it defaults to zero. A decimal point is not printed if d is zero. If there are more digits in the number than the field allows, an asterisk is printed in the first column of the field to indicate an overflow. If the number is negative, a minus sign is printed in the first column of the field. Any leading zeroes are suppressed. If string literals are included in the format field, the D format is required for numeric output.

Ew[.d]

The same as the D format, except that a minus sign is placed immediately to the right of the number if it is negative, and a space if it is positive.

Fw[.d]

The same as the D format, except that a minus sign is placed immediately to the left of the number if it is negative.

Kw

Converts the number to octal and outputs it using a total of w columns.

L6c or L6_c

Sets the floating fill character, which is normally a space, to c. The floating fill character is placed immediately to the left of numbers printed by the D and E formats. If c is numeric, the L6_c form is required.

L7c or L7_c

Sets the overwrite character, which is normally a space, to c. The overwrite character is the character in the buffer that is overwritten by numbers with a D, E, or F format. If c is numeric, the L7_c form is required.

L8c or L8_c

Sets the fill character, which is normally a space, to c. If STMA 6,7 has been issued, the fill character replaces all characters not used by D and E formats. If no STMA 6,7 has been executed, the fill character replaces leading zeroes only. If c is numeric, the L8_c form is required.

L9

Allows a repeat count to be read from the next expression.

L10

Applies a PRINT USING statement to the corresponding string expression as well as the console. The string must be dimensioned to at least 132 bytes. $FORMAT is an equivalent to L10.

L11

Copies the corresponding string expression into the buffer.

O

Used with the D, E, and F formats. An O immediately before one of the format characters suppresses printing if the number is zero.

P

Ends the line with a form feed character. On a DASHER terminal, this clears the screen.

Rn

The same as the A format, but right-justifies the string in the output buffer, by placing any pad spaces on the left of the string.

Sn

The same as the A format, but no pad spaces are added if the string is shorter than n.

Tn

Moves the current position in the output buffer to column n. Since the buffer is 132 bytes long, n must not exceed 132.

nX

Moves the current position in the output buffer n spaces. To move backwards, a negative value may be specified for n.

Z

Terminates the output line with a null character. If the Z format is not specified, the output line is terminated by a carriage return. Including a Z format ina PRINT USING statement has a similar effect to finishing a PRINT statement with a semi-colon.

If the USING_NULL switch is turned on, the Z format will suppress the printing of any terminating character. This is useful when the output is destined for a printer which chokes on null bytes.


$Q

$Q ------------ Determine the queue ID for a particular port

Type

U/BL command.

Syntax

$Q

Description

The $Q command displays all active local ports for this process including the message queue ID and the key (or global port).

See also

$M


QADD

QADD ---------- Adds two quadruple precision numbers

Type

U/BL command and statement.

Syntax

QADD sum$, num$, num$

Arguments

sum$ | A string variable dimensioned to at least 8 bytes, which receives the result of the addition.
num$ | A string variable which contains a number as a result of a QLOAD or other quadruple-precision statement.

Description

Quadruple precision arithmetic is standard, and no special statements are required to achieve this precision. For compatibility with earlier versions of Business Basic, however, arithmetic can be performed using 8-byte strings and the special quadruple precision statements. Q-strings require no initialisation apart from being dimensioned.

The QADD statement adds two Q-strings together, storing the result in a third.

Example

00010 DIM A$[8],B$[8],C$[8],D$[8],E$[8]

00020 INPUT "Enter 4 numbers to sum...",A,B,C,D

00030 QLOAD A$,A

00040 QLOAD B$,B

00050 QLOAD C$,C

00060 QLOAD D$,D

00070 QADD E$,A$,B$ : Sum A+B into E

00080 QADD E$,E$,C$ : Add C to E

00090 QADD E$,E$,D$ : Add D to E

00100 QDIV E,E$,4 : Divide E by 4

00110 QSTORE G,E$

00120 PRINT "The average is ";E;"and the sum is ";G

See also

QDIV

QLOAD

QMUL

QSTORE

QSUB


QDIV

QDIV ---------- Divides a quadruple precision number by a normal integer

Type

U/BL command and statement.

Syntax

QDIV quotient, dividend$, divisor [,remainder, error_code]

Arguments

quotient | A numeric variable which receives the result of the division.
dividend$ | A string variable which contains a number as a result of a QLOAD or other quadruple-precision statement, which is divided by the divisor.
divisor | A numeric variable which contains the number to be divided into the dividend$.
remainder | A numeric variable which receives the remainder. If this variable is omitted, the remainder is lost.
error_code | A numeric variable which receives an error code if the division is invalid.

Description

The QDIV command allows a q-string to be divided by a normal number, with an option to store the remainder and trap an illegal division (division by zero).

See QADD for an example, and an explanation of the Business Basic quadruple precision statements.

See also

QADD

QLOAD

QMUL

QSTORE

QSUB


QEDIT

QEDIT ---------- Allows formatted output of the Q-arithmetic numbers

Type

U/BL Statement.

Syntax

QEDIT string1$,string2$

Arguments

string1$ | A string variable or substring containing an edit mask. The results of QEDIT are stored in this string
string2$ | A string variable containing the Q-arithmetic number to be edited (that is, string2$ is the result of a QLOAD, QADD, QSUB, QMUL, or QDIV). It must be DIMensioned to at least 8 bytes (if not, it fails the Q-arithmetic statement).

Description

The Q-arithmetic format allows large numbers to be represented in the Q-arithmetic format (up to 19 digits of significance). You can use QEDIT to edit these numbers for output.

You cannot edit all numbers that can be stored in Q-arithmetic format. This is because the QEDIT instruction performs the editing in a two step process. The number stored in string2$ is separated into a high-order number and a low order number. The low-order number has a maximum of 9 decimal digits, and so its largest magnitude is 999,999,999. The high-order number is then the high-order ten digits, with the restriction that it must fit into a normal BASIC number. Therefore, in a double precision BASIC, the largest number that can be QEDITed is 2,147,483,647,999,999,999 (the largest number string2$ can hold is 4,611,686,014,132,420,609).

In triple precision BASIC, all numbers that can be stored in a Q-arithmetic string can be QEDITed.

QEDIT takes the Q-arithmetic number in a string2$ and edits it into the mask in string1$. When this statement is completed, you can print or display the mask string directly to an ASCII output device.

This statement is a simplified PRINT USING for Q-arithmetic numbers.

The way that QEDIT works is to take the decimal digits of the number in a right-to-left (least significant to most significant) order, and to place them into the mask string, also in a right-to-left (high subscript to low subscript) order.

Note: As the mask may be a substring, you can set up a large string with submasks for several numbers, and QEDIT multiple times into the different areas of the large mask.

The rules for replacement of mask characters is as follows:

- (minus sign) | The algebraic sign of the number (- if the number is less than zero; (space) otherwise) is placed into the mask string where the minus sign is encountered. If the mask string contains no minus sign, the sign is placed immediately to the left of the most significant digit.
# (pound sign) | # in the mask denotes a position into which the next decimal digit will be placed. The digits of the number replace the #'s in a left-to-right manner.
Any other characters (such as comma, decimal point) | All other characters are left in the mask, that is, they are skipped over.

After all the digits from the number have been placed into the mask string and the sign has been inserted, leading characters in the mask will be replaced by blanks, moving left-to-right, until reaching a non-zero digit, a minus sign, or a decimal point, at which point blanking will cease (all characters to the right remain).

If all digits are zero (that is, the value stored in string2$ is zero) and there is no decimal point in the mask, the least significant zero (the one in the units position) is displayed and all the characters to the left of it are blanked; all characters to the right of it remain.

If the mask is not large enough to hold the number (that is, it has fewer #s than the number of significant digits), the leftmost character of the mask string is set to asterisk (*). The BASIC program may test for the overflow condition by 'IF MASK$(1,1)="*"THEN ...'.

Possible errors:

BASIC error #16 (Arithmetic Overflow) - The number stored in string2$ is larger than 2,147,483,647,999,999,999. (This error should not occur in triple precision Business BASIC).

BASIC error #34 (Illegal Format String) - If the mask string has a zero length.

BASIC error #64 (Incorrect Argument Type) - If string2$ does not have a current length of at least 8.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

DEMONSTRATES THE QEDIT INSTRUCTION

100 DIM Q$ (8) ,MASK$ (30) ,FMT$ (80)

  FMT$="E12.0 ,' =.X ',E12.2,' =Y',A30,' =X*Y'"

110 READ X,Y

  IF X=999 THEN END

120 QMUL Q$, X, Y

  MASK$="###,###,###,###,###,###.## -"

  QEDIT MASK$, Q$

  PRINT USING FMT$, X, Y, MASK$

  GOTO 110

200 DATA 123456789,10000000

201 DATA -987654321,123456789

202 DATA 0,-99999999

203 DATA -1023456789,-1023456789

209 DATA 99,0

When run, this program will produce the output shown below:

123456789 = X 100000.00 = Y 12,345,678,900,000.00 =X*Y

987654321- = X 1234567.89 =Y 1,219,326,311,126,352.69- =X*Y

0 = X 999999.99- =Y 00 =X*Y

1023456789- = X 1023456789- = Y 10,474,637,989,501,905.21 =X*Y


QLOAD

QLOAD -------- Loads a numeric expression into a string for quadruple-precision arithmetic

Type

U/BL command and statement.

Syntax

QLOAD qstring$,num_expr

Arguments

qstring$ | A string variable dimensioned to at least 8 bytes.
num_expr | Any numeric expression.

Description

The QLOAD command takes a normal number and stores it in a q-string for use by other q-statements.

See QADD for an example, and an explanation of the Business Basic quadruple precision statements.

See also

QADD

QDIV

QMUL

QSTORE

QSUB


QMUL

QMUL ---------- Multiplies two integers giving a quadruple-precision product

Type

U/BL command and statement.

Syntax

QMUL product$,num_expr,num_expr

Arguments

product$ | A string variable dimensioned to at least 8 bytes which receives the product of the multiplication.
num_expr | Any numeric expression.

Description

QMUL multiplies two normal numbers and stores the product in a q-string for use by other quadruple precision statements.

See QADD for an example, and an explanation of the Business Basic quadruple precision statements.

See also

QADD

QDIV

QLOAD

QSTORE

QSUB


QSTORE

QSTORE ---------- Converts a quad-precision string to a normal integer

Type

U/BL command and statement.

Syntax

QSTORE num_var, qstring$

Arguments

num_var | A numeric variable.
qstring$ | A string variable containing a quadruple precision number as a result of a quadruple-precision statement.

Description

The QSTORE command takes a q-string, normally produced by other quadruple precision statements, and converts it to an integer, placing the result in the num-var parameter.

See QADD for an example, and an explanation of the Business Basic quadruple precision statements.

See also

QADD

QDIV

QLOAD

QMUL

QSUB


QSUB

QSUB ---------- Subtracts one quadruple-precision number from another

Type

U/BL command and statement.

Syntax

QSUB result$,qnum$,subtrahend$

Arguments

result$ | A string variable dimensioned to at least 8 bytes.
qnum$ | A string variable containing a quadruple precision number as a result of a quadruple-precision statement, and from which the subtrahend$ is subtracted.
subtrahend$ | A string variable containing a quadruple precision number as a result of a quadruple-precision statement, which is subtracted from qnum$.

Description

The QSUB command subtracts one q-string from another, storing the result in a new q-string.

See QADD for an example, and an explanation of the Business Basic quadruple precision statements.

See also

QADD

QDIV

QLOAD

QMUL

QSTORE


RADD

RADD ---------- Adds a record file

Type

U/BL Statement.

Syntax

RADD FILE(channel,recnum),recbuf

Arguments

channel | A numeric expression specifying the channel number on which a data file has been opened
recnum | A numeric variable into which the newly assigned record number is returned
recbuf | A string variable containing the information to be written

Description

The RADD statement obtains the record number of the next available record, and writes the record buffer to the newly assigned record number. The record number is obtained exactly as when using the GETRNO. The record is written as in RWRITE.

You must make sure that the current length of the record string is at least as long as the record length for the file. The record length is set when the file is created and can be obtained by using the FCB$ function.

The RADD statement is designed for use with type D files. For type T files, use the WRITE FILE statement. For type I or J files, use KADD. If no basic records are available, a BASIC run-time error (# -142) occurs.

This statement updates the number-of-active-records field, the last-record-number-used field, and the first-deleted-record-number field in the FCB.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This statement demonstrates the use of the RADD statement. This allows the user to add records after entering the name field which goes in bytes 1-20 of the record.

Note: This program only adds records and does not add keys to the FILE.IX file (as RKADD example does).

10 DIM X$ (80)

20 OPEN FILE (0, 5) ,"FILE.DT" :OPEN FILE

30 X$=FCB$ (0)

40 RECLEN=ASC (X$ (26, 26)) *256+ASC (X$ (25, 25) :GET RECORD

: LENGTH FORM FCB

50 DIM REC$ (RECLEN)

55 REC$=FILL$ (0) :INITIALIZE REC$ TO ZEROES

60 INPUT USING " " ,"ENTER THE NAME " ,X$ :GET THE NAME

65 IF LEN (X$)=0 THEN GOTO 900

70 REC$ (1, 20)=X$ ,FILL$ (32)

80 RADD FILE (0, RN) ,REC$ :ADD RECORD

85 FLUSH FILE (0) :UPDATE FCB ON DISK

90 PRINT "RECORD" ;RN ;"JUST ADDED"

100 GOTO 60

900 CLOSE

  END


@REV

@REV ---------- Sets the programs revision bytes

Type

U/BL Statement.

Syntax

@REV rev1,rev2[,rev3]

Arguments

rev1 | A numeric constant specifying #REV1 in the range 0-255.
rev2 | A numeric constant specifying #REV2 in the range 0-255.
rev3 | A optional numeric constant specifying #REV3 in the range 0-255. If not specified, it is assumed to be 0.

Description

The @REV statement sets the three BASIC variables #REV1, #REV2 and #REV3 to the three values specified. These variables can be used like any ordinary numeric variable. The @REV statement also causes the BASIC compiler to output these revision values into bytes 43-45 of the program file's FCB.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

:

: This sample program shows the use of the @REV statement

:

10 @REV 2,5,1

20 DIM X$(8)

30 X$=#REV1,".",#REV2,".",#REV3

40 PRINT "REV=";X$

50 END


RADIOBUTTON

RADIOBUTTON ---------- Creates a radio button

Type

Windows Object Command

Syntax

RADIOBUTTON(ID, ROW, COL, HEIGHT, WIDTH, TEXT$, MODE [, STAT])

Arguments

ID | The unique handle used to identify the object
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT$ | The initial text to be displayed next to the radio button
MODE | Specifies how the statement (and subsequently, the object) will work.
STAT | Optional status return.

Description

This statement creates a radio button with the legend defined by the TEXT$ parameter. The subsequent operation of the radio button is controlled by the MODE parameter which, besides taking the value of any of the Standard Windows Object Flags, can be combined with the following, statement specific flag:

Value | Description
512 | When the item is selected, U/Gi returns the string @^n (where 'n' is the object's handle) to U/BL.

Radio buttons are usually employed to allow the selection of a single item from a set of mutually-exclusive possible options. This is achieved by putting the radio buttons into a radio group. This grouping is achieved by:

  1. Defining the individual radio buttons to have consecutive handles (the numbers need not be consecutive but there should be no other objects defined to have a handle numerically between that of the first and the last radio button in the group)

  2. Defining the first radio button in the group (the one with the lowest value handle) with the Standard Windows Object Flags, TABSTOP and GROUP set

  3. Defining all subsequent buttons in the group to NOT have the TABSTOP or GROUP flag set

  4. Defining the next Windows object(the one with the next highest handle after the last radio button in the group) to have the GROUP (and TABSTOP if appropriate) flag set.

Defining a radio group in this manner will result in the selection of any of the grouped buttons automatically de-selecting whichever of the other members of the group are currently selected. The grouped buttons therefore represent a collection of mutually exclusive options.

Note: When using the SETNUMBER statement against radio buttons that are in a radio group, the mutual exclusivity of the buttons is not respected. In other words, using SETNUMBER to change the state of a radio button only alters the state of that button, even if this will result in two buttons in the radio group from being selected at the same time.

See Also

Error codes

GETNUMBER

GETTEXT

SETNUMBER

SETTEXT

Standard Windows Object Flags


RANDOMIZE

RANDOMIZE --------- Initialize the random number generator

Type

U/BL command and statement.

Syntax

RANDOMIZE

Description

The RANDOMIZE statement sets the random number generator to a random starting point, to ensure that numbers produced by the RND function differ each time a program is run. If the RANDOMIZE statement is not used, RND will return the same series of random numbers each time a program is run.

See the RND function for an example of RANDOMIZE.

See also

RND


RAWKBD

RAWKBD ------------ Establish a key's raw value

Type

U/BL command and statement

Syntax

RAWKBD(n)

Arguments

n

A numeric expression that switches keyboard remapping on or off.

Description

This statement is used to establish a key's raw value. If this statement is switched on as follows:

RAWKBD(1)

then the keyboard will not be remapped through the Terminal Definition File. To switch remapping back on again, use the following statement:

RAWKBD(0)

Example

00010 RAWKBD(1) : SWITCH TDF REMAPPING OFF

:

: Examine keys' raw outputs here

:

00060 RAWKBD(0) : SWITCH TDF REMAPPING BACK ON

:


RDEL

RDEL ---------- Deletes a record

Type

U/BL Statement.

Syntax

RDEL FILE(channel,recnum)

Arguments

channel | A numeric expression specifying the channel on which the file is opened.
recnum | A numeric variable whose value specifies the record number to be deleted.

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RDEL statement performs a record delete. It deletes the record specified by the record number, and modifies the first four bytes. The first byte is set to the hexadecimal value "EA" (234 decimal) and the next three bytes are set to the last record number that was deleted. If there are no other deleted records in the chain, this value is zero.

This information is used when a GETRNO, RADD, or RKADD statement is executed. It allows deleted records to be used again. Do not change this information if dynamic record allocation is used.

A deleted record can be read, however, the programmer must check that the records that are processed are not deleted. If a deleted record is deleted again, a BASIC run-time error (# -135) occurs. If you attempt to delete a record number greater than the maximum number of records, a BASIC run-time error (# -137) occurs.

This statement updates the number-of-active-records field, the last-record-number-used field, and the first-deleted-record-number field in the FCB are all updated by this statement.

Note: A record is automatically unlocked (see SUNLOCK) when it is deleted.

Example

This is a program which allows the user to specify which records will be deleted.

10 DIM X$ (10)

20 OPEN FILE (0, 5) ,"FILE.DATA"

30 INPUT USING " " ,"ENTER THE RECORD # TO DELETE OR 'E' TO END " ,X$

40 IF X$="E" THEN GOTO 900

50 RN=VAL (X$, IER)

60 IF IER THEN

  PRINT "INVALID NUMBER"

  GOTO 30

  END IF

70 RDEL FILE (0, RN) :DELETE RECORD #

75 FLUSH FILE (0)

80 GOTO 30

900 CLOSE

  END


READ

READ --------- Assigns values from DATA statements to variables

Type

U/BL command and statement.

Syntax

READ variable [,variable]....

Arguments

variable

A string or numeric variable which receives a value from the corresponding DATA statement.

Description

The READ statement takes one or more values from a DATA statement and assigns it to a variable. The number of values read corresponds to the number of variables supplied to the statement and has no connection with the number of values in each DATA statement. Each READ statement may access more than one DATA statement, or several READ statements may access one DATA statement. Often, programs are clearer if DATA s+-tatements are arranged to match READ statements.

The type of variable and the type of value read must match. A string value cannot be read into a numeric variable or vice versa.

Variables can be subscripted if desired.

For examples, see the DATA and RESTORE statements.

See also

DATA

RESTORE


READ FILE

Type

U/BL command and statement.

Syntax

READ FILE (channel[,byte]),variable[,variable]....

Arguments

channel | A numeric expression for the channel number used to OPEN the file.
byte | A numeric expression representing the byte position at which to start READing the file.
variable | A string or numeric variable which receives a value from the file.

Description

The READ FILE statement reads the number of bytes from a file needed to fill the variables supplied as arguments. If more than one variable is supplied, a separate input is performed for each. If no byte position is specified, READ FILE begins READing from the current position. The file pointer is updated to point to the first byte after the data read.

The READ FILE statement reads binary data from a file; it should be matched with the WRITE FILE statement.

READ FILE [16] is a special case which behaves as a READ statement, and retrieves its values from DATA statements. It ignores the byte argument.

If the end of the file is reached, the variable being READ is null filled if it is a string or set to zero if it is numeric. The EOF function can be used to detect that the end of the file has been reached.

Example

# list

00010 DIM X$[60], Y$[60]

00020 OPEN FILE[0,11],"MYFILE"

00030 LET A=1234 \ B%=4312

00035 LET X$ = "Nothing should be done in haste but gripping a flea"

00040 WRITE FILE[0],A,B%,X$

00050 CLOSE FILE[0]

00060 OPEN FILE[0,13],"MYFILE"

00070 READ FILE[0],C

00080 READ FILE[0],D%,Y$

00090 PRINT C,D%,Y$

00095 PRINT

00100 CLOSE FILE[0]

* run

1234 4312 Nothing should be done in haste but gripping a flea

See Also

DATA

READ

WRITE FILE


READLOCK

READLOCK ---------- Allows reading of records that were locked using the SLOCK statement

Type

U/BL Statement.

Syntax

READLOCK FILE(channel) ON

READLOCK FILE(channel) OFF

Arguments

channel

A numeric expression specifying channel number on which a file is opened

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The READLOCK statement sets or resets a flag that allows the user to read a record that has been locked using SLOCK. A read is not allowed when a file is locked via the FILELOCK statement, even if the READLOCK flag has been set.

By default, this flag is set OFF. In the OFF state, a run-time error (#ERR=30) occurs when attempting to read one or more records that span an area locked by another user. If this flag is set to ON, the record can be read without a run-time error.

Note: If READLOCK is ON, AUTOLOCK is considered to be OFF.

READLOCK only allows SuperDOS-type access (RREAD, RKNEXT, and so on) to SLOCKed records. READLOCK ON does not prevent a run-time error when accessing SLOCKed records using READ FILE statements.

Note: By default the READLOCK statement is not supported under Windows. Version of U/BL 2.20 and above have been enhanced to provide their own locking mechanism to facilitate this functionality. This allows the READLOCK statement to work in the same way as under SuperDOS BBASIC by setting the BBSLOCK environment variable to TABLE (BBSLOCK=TABLE) on Windows platforms. However, there is a performance penalty, because this locking mechanism involves recording the lock details in the U/BL run-time, as there is no operating system mechanism for providing this functionality.

Example

This program reads the first 10 records of a file even if they are locked.

10 DIM REC$ (800) :ASSUME REC LEN<=80

20 OPEN FILE (1, 5) , "FILE.DT" :OPEN FILE

30 READLOCK FILE (1) ON :ALLOW LOCKED RECS TO BE READ

40 RN=1

50 RREAD FILE (1, RN) ,REC$, 10 :READ 10 RECORDS

60 CLOSE

70 END


REM

REM ---------- Allows comments in a program

Syntax

REM text

or

:text

Arguments

text  Any valid ASCII text string

Description

The REM statement allows you to document a program, by entering an ASCII text string. The statement produces 0 bytes of code when the program is compiled. You can use as many lines as you want, without affecting the size of the code (unless you use line numbers, but this is not recommended.)

The colon character ':' works in exactly the same way as the REM statement. You can place a ':' anywhere on a line, and the compiler will ignore all text after the ':'. This allows you to enter comments in lines of program code.

The REM statement must always be used at the beginning of a line.

Example

REM This program prints the values of y

10 FOR I=1 TO 50 : this sets up the counter

20 PRINT "Y=";I

30 NEXT I : this is the last instruction

40 END


RENAME

RENAME ---------- Change the name of a file on disc

Type

U/BL command and statement.

Syntax

RENAME oldname newname ...

Arguments

oldname | The name of a file in the current directory.
newname | A new name for that file.

Description

RENAME changes a file name from 'oldname' to 'newname'.


RENUM

RENUM ---------- Renumbers a sequence of line numbers within a program

Type

U/BL command and statement

Syntax

RENUM

Description

The RENUM command acts upon a SAVEd file in memory. It renumbers a sequence of line numbers within a program. It prompts for:

  Starting line number of range .....[sssss] :

  Ending line number of range .......[eeeee] :

  New line number for start of range [00010] :

  Line number increment .............[00010] :

where sssss is the first line number in the current program and eeeee is the last line number. The new line number for the start of range and the line number increment both default to 10.

See also

DUP

ERASE

RNAM


_RENUMBB

RENUMBB ---------- Calls the Business Basic utility "RENUM"

Type

U/BL command.

Syntax

RENUMBB

Description

The RENUMBB command calls the Business Basic utility "RENUM". The utility is in the utility program library, ubblib, so the BBLIB environment variable must be set up to point to the ubblib file in the U/BL installation directory. This utility LISTs the program, re-numbers and then re-ENTERs it. Consequently it is much slower than the C version.

This version does handle ENTRY statements.

The environment variable BBSTRINGS must be set to at least 140000. This is because the program uses a very large string.

As this utility makes use of the common block, the contents of the common block may be in an indeterminate state after the utility has been used to re-number a program.


REPLACE

REPLACE -------- Saves the program in memory but does not retain the contents of its variables

Type

U/BL command and statement.

Syntax

REPLACE [program$]

Arguments

program$

A string literal or variable containing a valid filename, optionally including a pathname.

Description

The REPLACE statement saves the program in memory but it doesn't retain the contents of its variables, the GOSUB stack, or the position reached for a CON statement to resume from, unless the environment variable BBEXTENSION is set to include B32 or the environment variable BBSAVE is set. If the environment variable BBEXTN is set, then the specified ". extension" is appended to program$.

If the environment variable BBPROGS is set, the program is always be saved in the first directory specified unless a pathname is used.

If a file with the specified name already exists, it is overwritten.

If the program$ parameter is not specified, the current program name is used. This name is set by the last LOAD, RUN, SAVE or REPLACE statements and defaults to SCRATCH. If a pathname is not specified within the program$ parameter, the program is saved in the current directory. The current program name does not include a pathname.

Example

* load "test

* list

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

* 25 ;"World

* list

00010 REM This is a test program

00020 PRINT "Hello"

00025 PRINT "World"

00030 END

* replace

* load "test

* list

00010 REM This is a test program

00020 PRINT "Hello"

00025 PRINT "World"

00030 END

See also

$IREPLACE

$ISAVE

BBSAVE

REPLACEV

SAVE

SAVEV


REPLACEV

REPLACEV ---------- Save the program in memory, along with the contents of its variables

Type

U/BL command and statement.

Syntax

REPLACEV [program$]

Arguments

program$

A string literal or variable containing a valid filename, optionally including a pathname.

Description

The REPLACEV command saves the program in memory, along with the contents of its variables, the GOSUB stack, and the position reached in the program for a CON statement to resume from. The REPLACEV statement must be included in the program which is to be REPLACEVed. If a file with that name already exists, it is overwritten.

If the environment variable BBEXTN is set, then the specified ".extension" will be appended to the program$ argument. If the program$ argument is not specified, the current program name is used. This name is set by the last LOAD, RUN, SAVE or REPLACE statements and defaults to SCRATCH.

If a pathname is not specified within the program$ parameter, the program is saved in the current directory. The current program name does not include a pathname. If the environment variable BBPROGS is set, the program is always saved in the first directory specified unless a pathname is used.

Example

* load "myprog

* list

00010 REM This is a test program

00020 LET X=3 \ Y=4

00030 REPLACEV "MYPROG

* run "myprog

* ;x;y

 3 4

* new

* ;x;y

 0 0

* load "myprog

* ;x;y

 3 4

See also

$IREPLACE

$ISAVE

BBSAVE

REPLACE

SAVE

SAVEV


REPLY

REPLY ---------- Sends a response to a task input

Type

U/BL Statement.

Syntax

REPLY task, message[,bits]

Arguments

task | A numeric expression that specifies where the REPLY message is sent
message | A string to be sent to the task you specified
bits | An optional numeric constant or numeric variable. If this argument is present, and if bit 0 of the numeric constant or variable is 12,all characters are handled as if keyed directly from the keyboard (for example, Ctrl C), and your task can REPLY to a task that is using a RINGBUF alternate buffer.

Description

This statement sends the message to the task you specify. The message enters the ring buffer as if it has been input from a terminal keyboard. Because of this, in order to terminate the input statement, you must include the unpend character as part of the message.

You can use the REPLY statement in batch processing, by using REPLY to reply to your own task, and then performing a CHAIN or SWAP to another program. The message sent in the REPLY is buffered, and then used when an INPUT is processed. When you use REPLY to reply to your own task, you must have a port assigned. You do not need to have a port assigned if you are not using REPLY to reply to a task that is not your own task.

The system ring buffers for a port can only hold 79 bytes, so you must make sure that the message string is dimensioned to a maximum of 79 bytes to match the system ring buffers. If you try to REPLY and there is not enough room in the ring buffer, none of the message string is moved, and a run-time error (#ERR=#90) occurs.

If you try to REPLY to a task that has no port, there is no ring buffer in which to store the message, and so the message is stored in a temporary storage area. However:

  • If the task was not waiting for a message to be input, the temporary storage cannot be used and a run-time error (#ERR=#90) occurs.

  • If the ring buffer of the task's port for which the REPLY instruction is intended has been changed (using the RINGBUF instruction), a run-time error (#ERR=54) occurs, unless the flag is present with bit 0 set.

  • If you attempt a REPLY to an invalid task number in the range 1 to 127, a run-time error (#ERR=54) occurs. If the invalid task is less than 1 or greater than 127, a run-time error of #ERR=-71 occurs.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


RESETIKEY

RESETIKEY ---------- Resets the IKEY pending flag

Type

U/BL Statement.

Syntax

RESETIKEY

Description

The RESETIKEY statement resets the IKEY pending flag. This is the flag that is set when interrupts are disabled via NOTIKEY (STMA 6,5) and an IKEY was encountered. If this flag is set, the IKEY logic is invoked as soon as YESIKEY (STMA 7,5) is executed. If this flag is reset, BASIC does not invoke the IKEY logic upon execution of the YESIKEY. The value of this flag can be accessed with the SYS(26) statement.

RESETIKEY is equivalent to STMA 8,3.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 8.


RESTORE

RESTORE ---------- Allows DATA statements to be re-read

Syntax

RESTORE [line number]

Arguments

line number

An integer that specifies the line number of a DATA statement.

Description

The RESTORE command resets the pointer that indicates which DATA statement values have been read. If you omit the line number, the program assumes the first DATA statement in the program. With a line number, RESTORE sets the pointer to the first value of the DATA statement at that line (or the first DATA statement following that line, if the line is not a DATA statement or does not exist).

Example

0010 PRINT "Menu"

0020 PRINT

0030 PRINT "1. Products"

0040 PRINT "2. Pricing"

0050 PRINT "3. Inventory"

0060 PRINT "4. Games"

0070 PRINT "5. End program"

0080 PRINT

0090 INPUT "Choose...",CHOICE

0100 IF CHOICE<1 OR CHOICE>5 THEN GOTO 10

0105 RESTORE

0110 FOR I=1 TO CHOICE

0120 READ NEXTPROG$

0130 NEXT I

0140 SWAP NEXTPROG$

0150 GOTO 10

0160 DATA"NASTIES","CUSTOMERS","BIT_BUCKET","FUN", "GOODNIGHT"

See Also

DATA

READ


RETURN

RETURN ---------- Returns control of a program from a subroutine

Syntax

RETURN

Description

The RETURN statement directs the programming language to return from a subroutine. The GOSUB is cancelled, and BASIC executes the statement that preceded the last GOSUB.

More than one RETURN may exist in a subroutine. A RETURN without an active GOSUB causes an error.

Example

1000 REM file opening subroutine

1010 LET IN_CH=$CHN

1020 OPEN ERROR, FILE[IN_CH,13],"INPUT_FILE"

1030 IF ERROR THEN

1040 LET X$=ERM$[ERROR];"while opening input file"

1050 RETURN

1060 END IF

1065 LET OUT_CH=$CHN

1070 OPEN_ERROR, FILE[OUT_CH=11],"OUTPUT FILE"

1080 IF ERROR THEN LET X$=ERM$[ERROR];"when opening output.file"

1090 RETURN

See Also

Shared Memory Procedures


RFORM

RFORM ---------- Specifies a record layout for use by the PACK and UNPACK statements

Type

U/BL command and statement.

Syntax

RFORM format

Arguments

format

An unquoted string containing codes representing the valid string formats.

Description

The RFORM statement specifies a record layout for use by the PACK and UNPACK statements. Although the specification of the layout can be done in the PACK and UNPACK statements themselves, placing the definition in an RFORM statement allows the specification to be done only once, regardless of how many times it is used.

Any leading or embedded spaces in an RFORM statement are ignored. The following codes are permitted:

Format code

Meaning

An

Transfer n bytes from or to a string variable, but terminate the transfer at the first null character. If n is not specified it defaults to one.

B,C,D,E,F,G,H

Convert an unsigned integer to or from a 1, 2, 3, 4, 5, 6 or 7 byte field, respectively.

I,J,K,L,M,N,O,P

Convert a signed integer to or from a 1, 2, 3, 4, 5, 6, 7 or 8 byte field, respectively.

Sn

Transfer n bytes from or to a string variable, including any null characters in the string. If n is not specified, it defaults to one.

Un

This format is used for bit fields. PACK clears or sets the bit represented by n, which must be in the range 0 to 7, depending on whether the corresponding variable has a value of zero or not. UNPACK sets the variable to zero or one, depending on whether the bit is clear or set. If n is not specified it defaults to zero.

This format does not increment the pointer into the record string, so that several U formats may follow each other to define several bit fields to be used in a single byte. A positioning format (+ or @) should follow U statements to move the pointer.

Zn

PACK fills the record string with nulls and sets its length to n. The Z format must be the first non-space character in RFORM if it is used. If n is not specified it defaults to the maximum length of the record. UNPACK ignores the Z format.

*n

Repeats the preceding format n times, corresponding to a numeric array variable with at least n elements. The preceding format must be one of the numeric formats B-F or I-N. If n is not specified it defaults to 1.

+n

Skips n bytes of the record string. If n is not specified it defaults to 1.

@n

Positions to byte n of the record string. The default for n is one, which is the first byte of the string. All the above codes must be upper case.

Example

See the PACK and UNPACK statements for examples of the RFORM statement.


RGSTACK

RGSTACK ---------- Resets the GOSUB/RETURN stacks

Type

U/BL Statement.

Syntax

RGSTACK

Description

The RGSTACK statement resets the GOSUB/RETURN stacks. BASIC keeps a stack for the GOSUB/RETURN information, so that subroutines can return to the correct place.

After RGSTACK is executed, BASIC considers itself to be executing main line code. You can use this for error processing rather than setting an error code and returning back through a series of GOSUBs, RGSTACK can remove all of the pending RETURNs and the error logic can branch back to the main loop of the program.

RGSTACK is equivalent to STMA 8,2.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 8.


RINGBUF

RINGBUF ---------- Sets a user-defined ring buffer for a port

Type

U/BL Statement.

Syntax

RINGBUF port, buffer[,bits]

Arguments

port

A numeric expression that specifies the port's new ring buffer.

buffer

You must use DIM to dimension this to at least 9 bytes the first 8 bytes are used as follows:

  • 1-1 - set to 0DBH by token processor. Must be left alone.

  • 2-2 - overflow flag. If set to 1, then at least one byte was received by the port when there was no room to store it.

  • 3-4 - offset to head. This is where the next byte received by the port will be stored.. This offset is relative to byte 9 of the buffer (for example, an offset of 1 is byte 10).

  • 5-6 - offset to tail. This is one byte beyond where the last byte was removed (that is, where the next byte to extract is located). This offset of relative to byte 9.

  • 7-8 - the length of the buffer space. Set to the dimension of <str var> -8.

bits

An optional numeric constant or numeric variable. If present, and if bit 0 of the numeric constant or variable if 1, the buffer will work like the default ring buffer, for IKEY and control characters.

Description

The RINGBUF statement is designed to be used primarily when communicating with devices attached to serial ports. Normally, U/BL provides 80-byte ring buffers. However, sometimes a program needs to communicate with devices that send characters that send characters at speeds that fill up the buffer faster than it can be emptied, and one solution to this is having a larger ring buffer.

A ring buffer is a storage space in memory, which has a head and a tail. When characters are received by the port, they are stored at the head, and, as the user fetches them, they are removed from the tail. When either the head or the tail reaches the end of the buffer, it wraps around to the start. If the head ever catches up with the tail, the buffer is full and the byte cannot be stored.

When the RINGBUF statement is invoked, U/BL begins storing bytes received by the port at the head given by bytes 3-4 of the buffer. This is the offset relative to byte 9 of the buffer. Each time a character is received and stored, the head is incremented by 1 unless it matches the tail.

When the user extracts a byte or bytes from the buffer, the tail offset should be set to the offset where the last byte was extracted.

If the head catches up with the tail, an overflow has occurred and at least one data byte has been lost. Byte 2 of the buffer is set to 1, and this value stays at 1 even after more room has been made in the buffer by removing some bytes from the tail. It is the user's responsibility to examine and reset this byte.

You can also choose to use more than one buffer. You can create additional buffers as long as there is room in memory for them. The user then toggles among them by executing another RINGBUF to the same port, but using a different buffer. You need to initialize each buffer before it is used. In this way, a program can toggle between buffers when the head exceeds a certain size. If bytes are only removed from an inactivated buffer using this method, there is not need to reset the tail.

This statement does not change the current length of the string. The string is used to buffer, even if the current length is zero. The user cannot, of course, access any bytes beyond the current length. Therefore, the string must be filled with nulls before executing the RINGBUF statement. When the RINGBUF statement is executed, the token processor attempts to allocate the specified port to your task. If it is already allocated,a BASIC error (#78) occurs.

Whenever the port is deallocated, and either the program ends, or a CHAIN or SWAP is performed, the ring buffer is set back to the system ring buffer.

Possible errors are as follows:

54 | invalid task number
55 | port already allocated
80 | first byte of ring not set to 0DB by token processor
82 | head or tail beyond buffer size of string is less than 9
89 | invalid port number - not a configured port

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


RKADD FILE

RKADD FILE ---------- Adds a record and key to the file

Type

U/BL Statement.

Syntax

RKADD FILE(channel 1,recnum),
  INDEX(channel 2,ixbuf,ixkey,oprslt),recbuf

Arguments

channel 1 | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which the record number is assigned.
channel 2 | A numeric expression specifying the channel number on which an index file is opened.
ixbuf | A string dimensioned to at least 544 bytes (using DIM). This is the index buffer used by U/BL.
ixkey | A string variable that contains the key to be added to the index file.
oprslt | A numeric variable into which the result of the RKADD is stored. If this is non-zero, the key was not added.
recbuf | A string variable containing the record information to be added to the data file.

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RKADD statement adds a record to the data file and then adds a key to the index file. This is the same operation as performing a RADD operation followed by a KADD operation. As in RADD, the newly-assigned record number is returned in the recnum argument. Also as in RADD, the record string must have a current length at least as large as the record length of the data file. If the data file is full, the program ends with a BASIC run-time error (#-142), and the key is not added.

The operation result variable oprslt is returned with a zero if the key is added, and a non-zero if it is not added. The only reason that a key is not added is if you attempt to add a duplicate key to an index that does not allow duplicates (file type I). If the index is full and the data file still has room, the data record is added, but the program ends with a BASIC run-time error (#-142), and the index key is not added. Be aware that the record is added before the key and therefore if a key is not added, there will be a record in the data file without the key in the index file.

The key must be dimensioned, using DIM, to be at least as large as the key length of the index file. The index buffer must be dimensioned, using DIM, to be at least 544 bytes.

The number-of-active-records field, the last-record-number-use field, and the first-deleted-record-number field in the FCB are all updated by this statement.

Note: You cannot use the POS function as a numeric expression in the RKADD statement.


RKDEL FILE

RKDEL FILE ---------- Delete a record and key from any file

Type

U/BL Statement.

Syntax

RKDEL FILE(channel 1, recnum),
  INDEX(channel 2,ixbuf,oprslt)

Arguments

channel 1 | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable which specifies the record number to delete.
channel 2 | A numeric expression specifying the channel number on which an index file is opened.
ixbuf | A string dimensioned to at least 544 bytes (using DIM). This is the index buffer used by U/BL.
ixkey | A string variable that contains the key to be deleted from the index file.
oprslt | A numeric variable into which the result of the RKDEL is stored. If this is non-zero, the key was not found.

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RKDEL statement deletes the specified record from the data file, and then deletes the key from the index file. This is the same as performing an RDEL operation and a KDEL operation. If the key is not found, the operation result (oprslt) is set to non-zero. The key is not used to determine which record number to delete. The record number is specified in RKDEL, and is deleted independently of the index file key. It is best to perform a KFIND operation first, to retrieve the second number.

The dimension of the key string must be at least as large as the size of the key in the index. The dimension of the index buffer must be 544 bytes.

The number-of-active-records field, the last-record-number-used field, and the first-deleted-record-number field in the FCB are all updated by this statement.

Note:

  • The RKDEL statement can cause a run-time error (#8) if the key is not the proper key for the specified record number (deleted record chain needs to be rebuilt).

  • You cannot use the POS function as a numeric expression in the RKDEL statement.

  • A record is automatically unlocked when it is deleted (see SUNLOCK)


RKNEXT FILE

Type

U/BL Statement.

Syntax

RKNEXT FILE(channel 1 recnum)
   INDEX(channel 2,ixbuf,ixkey,oprslt),recbuf[,num]

Arguments

channel 1 | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which the record number is assigned. This is the record number associated with the next index file key.
channel 2 | A numeric expression specifying the channel number on which an index file is opened.
ixbuf | A string dimensioned to at least 544 bytes (using DIM). This is the index buffer used by U/BL. The information in this string must have been set by a previous key read.
ixkey | A string variable into which the next index file is returned.
oprslt | A numeric variable into which the result of the RKNEXT is stored. If this is 4, then there is no next key and teh end of the index has been reached.
recbuf | A string variable into which the record information is to be read from a data file
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If this is not included, 1 is assumed. The number of records must be less than or equal to 255. The Business BASC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low bye is used (that is, num=MOD(num,256]).

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RKNEXT statement reads the next key from the index file, and then reads the record from the data file associated with the key. This is the same as performing KNEXT followed by RREAD.

The next key is the next key found in the index file buffer. The buffer must contain valid index buffer information. This information is set by performing a KFIND or RKREAD operation. When it has been set, you can perform repeated KNEXT, RKNEXT, KPREV, or RKPREV statements by using the same index buffer. If you perform a KDEL, RKDEL, KADD or RKADD operation usin the same buffer, you need to reset the buffer by KFIND or RKREAD before executing any next or previous key statements. To allow these functions to work, you must not modify data in the index buffer.

The operation result variable oprslt is returned with a zero if the next key was found. If there are no more keys in the index, the operation result is returned with a 4.

When the key is found, RKNEXT moves the key from the index file to the specified key field, moves the associated record number to the record number field, and reads the specified number of records into the read buffer string, starting with the returned record number. The current length of the record buffer string is set to the number of bytes read.

If more than two index files are being processed but only next or previous statements are being performed on one of the files, only two buffer strings are needed. Use one buffer string on the file that is being used to process the next and previous statements, and use the other buffer for the other index files.

You must dimension the key to be at least as large as the key length of the index file. The index buffer must be dimensioned, using the DIM statement, to at least 544 bytes. The record buffer must be at least as large as the number of bytes that are to be read - use the DIM statement to do this.

When performing next or previous key statements, the buffer string in the program contains the last index block processed. To improve processing speed, U/BL uses this block as is, and does not read it again. Therefore, if another user is adding or deleting keys at the same time as your are working through the index, you might miss some keys or get some keys that have been deleted. To remedy this, you can use repeated KFIND or KNEXT operations, with a proper adjustment of the last key used.

If any of the records to be read are beyond the end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken), and the current length of the record buffer is set to the number of bytes actually read. Data up to the physical end of file us transferred into the record buffer. In this way, any data, whether or not intelligible, that exists in the file beyond the desired records that has been read, is also read into the record buffer until the entire length of the file has been read. The extra data may include full or partial-length records beyond the maximum record number stored in the FCB.

Note: You cannot use POS as a numeric expression in the RKNEXT statement.


RKPREV FILE

RKPREV FILE ---------- Reads one or more records from the previous key's record

Type

U/BL Statement.

Syntax

RKPREV FILE(channel 1, recnum)
  INDEX(channel 2,ixbuf,ixkey,oprslt),recbuf[,num])

Arguments

channel 1 | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which the record number is returned. This is the record number associated with the previous index file.
channel 2 | A numeric expression specifying the channel number on which an index file is opened.
ixbuf | A string dimensioned to at least 544 bytes (using DIM). This is the index buffer used by U/BL The information in this string must have been set by a previous key read.
ixkey | A string variable into which the previous index file key in returned.
oprslt | A numeric variable into which the result of the RKNEXT is stored. If this is 4, then there is no previous key - the beginning of the index has been reached.
recbuf | A string variable into which the record information is to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than or equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num =MOD(num,256) ).

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RKPREV statement reads the previous key from the index file, and then reads the record from the data file associated with the key. This is the same as performing a KPREV followed by an RREAD operation.

The previous key is the previous key found in the index file buffer. The buffer must contain valid index information. You set this information by performing a KFIND or RKREAD operation. Once set, repeated KNEXT, RKNEXT, KPREV, or RKPREV statements can be performed if the same index buffer is used. If you perform a KDEL, RKDEL, KADD or RKADD operation using the same buffer, reset the buffer by KFIND or RKREAD before any next or previous key statements are executed. To allow these functions to work, data in the index buffer string must not be modified.

The operation result variable oprslt is returned with a zero if the previous key was found. If there are no more keys keys in the index, the operation result is returned with a 4. When the key is found, RKPREV moves the key from the index file to the specified key field, moves the associated record number to the record number field, and reads the specified number of records into the record buffer string starting with the returned record number. The current length of the record buffer string is set to the number of bytes read.

If more than two index files are being processed but only next or previous statements are being performed on one of the files, only two buffer strings are needed. Use one buffer string on the file with which the next and previous statements are being processed, and the other buffer can be used for all the index files. Only the contents of an index buffer string need to be saved if you are going to do a next or previous statement.

The key must be dimensioned, using the DIM statement, at least as large as the key length of the index file. The index buffer, using the DIM statement, must be dimensioned to at least 544 bytes. The record buffer must be dimensioned , using the DIM statement, to at least as large as the number of bytes that are to be read.

When performing next or previous key statements, the buffer string in the program contains the last index block processed. To improve processing speed, U/BL uses this block as is and does not re-read it. Therefore, if another user is adding or deleting keys at the same time as you are working through the index, you might miss some of the added keys or get some keys that were just deleted. If this is a problem, you can use repeated KFIND or KNEXT operations with a proper adjustment of the last key used.

If any of the records to be read are beyond the end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 1 (but no error return is taken), and the current length of the record buffer is set to the number of bytes actually read. Data up to the physical end-of-file is transferred into the record buffer. Therefore any data, whether or not intelligible, that exists in the file beyond the desired record that have not been read, will also be read into the record buffer until the entire length of the file has been read. This extra data may include full or partial-length records beyond the maximum record number stored in the FCB.

Note: You cannot use the POS function as a numeric expression in the RKPREV statement.


RKREAD FILE

RKREAD FILE ---------- Reads one more records by a specified key

Type

U/BL Statement.

Syntax

RKREAD FILE(channel 1,recnum)
  INDEX(channel 2, ixbuf,ixkey,oprslt),recbuf[,num]

Arguments

channel 1 | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which the record number is returned. This is the record number associated with the index file key.
channel 2 | A numeric expression specifying the channel number on which an index file is opened.
ixbuf | A string dimensioned to at least 544 bytes (using DIM). This is the index buffer used by U/BL. The information in this string must be saved if you are going to perform a next or previous index access.
ixkey | A string variable into which contains the index file key for which to search. If the key is not found, the next key in the index is moved into this string.
oprslt | A numeric variable into which the result of the RKNEXT is stored. If this is 1 or 2, the key was not found, but the next key was moved to the key field above. If the specified key is greater than the last key, this field is set to 4. If the specified key is found, this field is set to 0..
recbuf | A string variable into which the record information is to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num=MOD(num,256)).

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The RKREAD statement searches for the specified key in the index file. If the key is found, the records are read into the record buffer This is the same as performing KNEXT followed by RREAD if the key was found.

If the key is not found, the next key in the index is moved into the key field, and its associated record number is moved into the record number variable, but the record is not read. In this case, the operation result is set to 1 or 2. If the specified key is greater than the last key in the index, the operation result is set to 4, and the key and record number cannot be predicted.

If the key is found, its associated record number is moved into the record number field, and the operation result is set to 0.

If an operation result is 1 or 2, you can execute an RREAD with the record number that was returned, and the record associated with the key that was returned is read.

You must dimension the key to be at least as large as the key length of the index file. The index buffer must be dimensioned, using the DIM statement, to at least 544 bytes. The record buffer must be at least as large as the number of bytes that are to be read - use the DIM statement to do this.

The index buffer is set to the last lower level block to be read by along with 32 bytes of index level information. These 544 bytes are needed to perform next or previous key statements.

If any of the records to be read are beyond the end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken), and the current length of the record buffer is set to the number of bytes actually read. Data up to the physical end of file us transferred into the record buffer. In this way, any data, whether or not intelligible, that exists in the file beyond the desired records that has been read, is also read into the record buffer until the entire length of the file has been read. The extra data may include full or partial-length records beyond the maximum record number stored in the FCB.

Note: You cannot use POS as a numeric expression in the RKREAD statement.


RNAM

RNAM ---------- Renames a program variable to a new specified name

Type

U/BL command and statement

Syntax

RNAM

Description

The RNAM command acts upon a SAVEd file in memory. It renames a program variable to a new specified name. It prompts for:

Old name :

New name :

If there are no errors (for example, reserved word used, new name already exists), then the rename is carried out.

See also

DUP

ERASE

RENUM


RND

RND ----------- Returns a random number

Type

U/BL command and statement.

Syntax

RND(maximum)

Arguments

maximum

A numeric expression limiting the size of the random number returned.

Description

The RND function generates a series of random numbers which are always greater than or equal to zero and less than the numeric argument. U/BL only produces the same sequence of numbers the FIRST time the program is run. Therefore, to produce the same sequence of number again, you must exit U/BL and bring it up again. Otherwise a different sequence of numbers will be produced whether the RANDOMIZE statement is used or not.

Examples

1. Without RANDOMIZE, the same series of numbers is always produced.

00010 FOR I=1 TO 10

00020 PRINT RND(100);

00030 NEXT I

00040 PRINT

* run

53 56 13 3 0 13 68 99 10 50

* run

53 56 13 3 0 13 68 99 10 50

2. Adding RANDOMIZE to the program, makes the numbers differ for each run.

* 5 randomize

* list

00005 RANDOMIZE

00010 FOR I=1 TO 10

00020 PRINT RND(100);

00030 NEXT I

00040 PRINT

* run

52 27 63 50 28 18 69 37 29 80

* run

19 36 22 49 95 40 60 34 55 5

* run

69 85 67 85 81 64 50 32 22 38

See also

RANDOMIZE


ROLLBACK

Type

SQL Access command

Syntax

ROLLBACK([CONN$][,STAT])

Arguments

CONN$ | The connection identifier. This argument is optional, it is only required in programs that use multiple concurrent connections. If this argument is specified and the connection exists transactions will be rolled back for the specified connection. If the connection identifier is specified and that connection does not exist then an error status of 2 is returned. If the connection identifier is not specified then transactions will be rolled back for the current connection.
STAT | An optional parameter which receives the return status.

Description

The ROLLBACK statement rejects the previous set of SQL operations, discarding their changes and ensuring the target data files are not updated. The group of SQL operations rejected, the transaction, is the collection of queries run (via the EXEC statement) since the last transactional control statement (one of the COMMIT, ROLLBACK or LOGON statements). A transaction is not limited to one SQL Access cursor, a transaction is regarded as the effect of all of the EXEC statements run since the last transactional control statement.

If this statement is called with the optional status return, on successful rejection of the transaction, the ROLLBACK statement will return a value of 0. A status return of -1 indicates a failure discarding the transaction, if this occurs the program should use the SQLERR statement to determine the exact nature of the error.

The ROLLBACK statement is only supported when using datasources, which support transactional processing. For datasources which have no transactional support the ROLLBACK statement does nothing, as the effect of each EXEC statement is immediately consigned to disk, the effect of any SQL query cannot be subsequently discarded.

Example

@AddProd&#9;REM Subroutine to add a new product to the catalogue

REM

REM Uses service queries ADD_PROD and ADD_PRICING with

REM product details and pricing passed in DETAILS$ and CHARGE$

EXEC "ADD_PROD", DETAILS$, ER

IF ER=0 THEN

EXEC "ADD_PRICING", CHARGE$, ER

IF ER<>0 THEN

ROLLBACK (ER) : Cannot add pricing so don't add product

IF ER<>0 THEN GOSUB @SeriousError

ELSE

COMMIT (ER) : Update database

IF ER=0 THEN RETURN

END IF

END IF

REM Only reach here under error conditions

GOSUB @AddError

RETURN

See also

COMMIT

EXEC

LOGOFF


RREAD

RREAD ---------- Reads one or more records by record number

Type

U/BL Statement.

Syntax

RREAD FILE(channel,recnum),recbuf[,num]

Arguments

channel | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable specifying the record number to read.
recbuf | A string variable into which the record information is to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num=MOD(num,256)).

Description

The RREAD statement reads one more records sequentially into the record buffer, starting with the specified record number. The contents of the records are transferred to a record buffer that must be dimensioned to at least as large as the number of bytes to be read. This is the record length of the file multiplied by the number of records to read. The record length is set when it is created and can be determined by using the FCB$ function.

If any of the records to be read are beyond the end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken), and the current length of the record buffer is set to the number of bytes actually read. Data up to the physical end of file us transferred into the record buffer. In this way, any data, whether or not intelligible, that exists in the file beyond the desired records that has been read, is also read into the record buffer until the entire length of the file has been read. The extra data may include full or partial-length records beyond the maximum record number stored in the FCB.

The number of records num must be less than or equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. For example, if the numeric expression evaluates to a number greater than 255, only the low byte is used, that is, num=MOD(num,256).

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


RRNEXT

RRNEXT ---------- Reads one or more records starting at the next record

Type

U/BL Statement.

Syntax

RRNEXT FILE(channel,recnum),recbuf[,num]

Arguments

channel | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which the record number of the next record number is returned. This is one, plus the last record number that was read.
recbuf | A string variable into which the record information is to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num=MOD(num,256)).

Description

The RRNEXT statement read one or more records sequentially into the record buffer, beginning with the record number of the last record read, plus one. The last-record-read field in the FCB us set by RKNEXT, RKPREV, RKREAD, RREAD and RRNEXT.

The contents of the records are transferred to the record buffer, which must be dimensioned to at least as large as the number of bytes to be read. This is the record length of the file, multiplied by the number of records to read. The record length of a file is set when it is created, and can be found using the FCB$ function.

The RRNEXT sets the recnum variable to the first of the records to be read.

If any of the records to be read are beyond the end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken), and the current length of the record buffer is set to the number of bytes actually read. Deleted records are not skipped. Data up to the physical end of file us transferred into the record buffer. In this way, any data, whether or not intelligible, that exists in the file beyond the desired records that has been read, is also read into the record buffer until the entire length of the file has been read. The extra data may include full or partial-length records beyond the maximum record number stored in the FCB.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


RSTACKS

RSTACKS ---------- Reset the FOR/NEXT and GOSUB/RETURN stacks

Type

U/BL Statement.

Syntax

RSTACKS

Description

The RSTACKS statement resets the FOR/NEXT and the GOSUB/RETURN stacks. U/BL uses a push down stack to keep track of the nested FOR/NEXT loops. If a branch is performed before the loop is completed, the information is left on the stack. Whenever possible U/BL removes the unnecessary stack entries, but it is possible to over flow the stack.

U/BL also keeps a stack for the GOSUB/RETURN information so that subroutines can return to the correct place.

RSTACKS resets both of the above mentioned stacks. Once the RSTACKS statement is executed, U/BL considers itself to be executing main line code. This can be useful for error processing. Rather than setting an error code and returning back through a series of GOSUBs, the RSTACKS statement can remove all of the pending RETURNs and the error logic can branch back to the main loop of a program.

The RSTACKS statement is equivalent to the STMA 8,0 statement.


RUN

RUN ------------ Executes a program

Type

U/BL command.

Syntax

RUN [program$]

RUN [line_no]

Arguments

program$ | A string expression containing the name of the program to be RUN.
line_no | The line at which to start executing the program in memory

Description

The RUN command, without arguments, executes the program currently in memory. It clears all variables, unDIMensions any strings, RESTOREs any DATA statements, resets terminal characteristics and resets the random number generator before executing the program from the beginning. Any open files, file position pointers and file locks are undisturbed.

The RUN program$ command LOADs the program named in program$ into memory (clearing the memory in the process), and then performs the same actions as in the previous paragraph. See also the SWAP and CHAIN statements.

The RUN line_no command does not clear variables, unDIMension strings, or carry out the other actions performed by the other forms of the RUN command. It is similar to the CON command, but it begins executing a program at the specified line number rather than at the line following the point of interruption.

Examples

1. RUN the program currently in memory.

* run

2. RUN a program not in memory.

* run "myprog

3. RUN a program from a specific line.

* run 100

See also

CHAIN

CON

SWAP


RWNEXT

RWNEXT ---------- Writes one or more records at the next record number

Type

U/BL Statement.

Syntax

RWNEXT FILE(channel,recnum),recbuf[,num]

Arguments

channel | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable into which is returned the record number to which the first record is written.
recbuf | A string variable containing the record information to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num=MOD(num,256)).

Description

The RWNEXT statement writes one or more records from the record buffer, starting with the next record number. RWNEXT writes the number of bytes computed by multiplying the number of records by the record length. The record buffer must be dimensioned to at least as large as the number of bytes to be written. This number of bytes is written regardless of the current length of the record buffer.

RWNEXT computes the next record number by adding 1 to the last record number referenced by an RWRITE or RWNEXT statement. This provides a method by which you can sequentially write a file without having to keep track of the record numbers. The RWRITE also allows you to write a file in both sequential and random mode. To make maintenance of programs easier, use RWRITE instead of RWNEXT.

Note: RWNEXT assumes that the last RWRITE or RWNEXT only wrote one record.

If any of the records to be read are beyond the physical end of file, then as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken).

RWNEXT provides no record update capability. It does not use or modify the last-record-used field in the FCB as RADD does. In addition, it does not update the logical end-of-file for type T files, as WRITE does.

RWNEXT writes over deleted records. It is the responsibility of the programmer to make sure that deleted records are not processed, as this corrupts the deleted record chain, and causes a BASIC run-time error (#-135) when records are added.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


RWRITE

RWRITE ---------- Writes one or more records by record number

Type

U/BL Statement.

Syntax

RWRITE FILE(channel,recnum),recbuf[,num]

Arguments

channel | A numeric expression specifying the channel number on which a data file is opened.
recnum | A numeric variable specifying the record number to write..
recbuf | A string variable containing the record information to be read from the data file.
num | An optional numeric expression that specifies the number of records to be read into the record buffer. If omitted, 1 is assumed. The number of records must be less than equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num=MOD(num,256)).

Description

The RWRITE statement writes one or more records from the record buffer starting with the specified record number. RWRITE writes the number of bytes computed by multiplying the number of records by the record length. The record buffer must be dimensioned to at least as large as the number of bytes to be written. This number of bytes is written regardless of the current length of the record buffer.

If any of the records to be written are beyond the physical end-of-file, as many records as possible are transferred, the EOF flag is set, #ERR is set to 10 (but no error return is taken).

The RWRITE statement does not provide the ability to update records. It does use, and/or modify the last-record-used field (in the file control block), as RADD does. It does not update the logical end-of-file for type T files (as WRITE does).

RWRITE writes over deleted records. It is the programmer's responsibility to make sure that deleted records are not processed, as this corrupts the deleted record chain, and will generate a BASIC run-time error (#-135) when records are added.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


@SET

@SET ---------- Defines the field specifications for use in the '@' statements

Type

U/BL Statement.

Syntax

@SET field,field_specs

Arguments

field | A numeric expression that specifies the field to be defined. This must be greater than zero, and less than or equal to the number in the @DIM statement.
field_specs | A string variable containing the 9 bytes defining a field. The bytes are listed below.

Description

The @SET statement defines the field specifications for the fields to be used in the @GET, @GETFLD, @FORMAT, @INPUT, @PACK, @UNPACK, @PRINT AND @PUTFLD statements. If a field number that has not been defined is referenced in any of these statements, a run-time error (#ERR=86) occurs.

If the field specified in @SET is zero or greater than @DIM, then a run-time error (#ERR=86) occurs. If the current length of the string is less than 9, a run-time error (#ERR=84) occurs.

The information in the field specs string must be set as shown below:

Bytes

Description

1-1

Type of field:

A = Alpha

C = Crammed

J = Julian date

N = Numeric

2-3

Start position on the record string relative to 1.

4-4

Length of the field in the record (in bytes)

5-5

Reserved.

6-6

Format for numeric fields. XXY where 'XX' is the number of print positions and 'Y' is the number of decimal positions. This is ignored if the fields are not numeric.

7-7

Y coordinate (line) on CRT where field is displayed.

8-8

X coordinate (column) on CRT where field is displayed.

9-9

Flags byte. The bits in this byte are flags used by the various '@' statements. They are defined as shown below:

Bit | Description
0 | If set, the custom edit routine is called by the @INPUT statement.
1 | If set, the custom display routine is called by the @INPUT and @PRINT statements.
2 | If set, the field is skipped by the @INPUT statement.
3 | If set, this field is skipped during the @FORMAT, @PACK, @UNPACK and @PRINT statements.
4 | If set the field information entered by the user is not moved to the record string. Only use this in conjunction with the custom edit flag (bit 0)
5 | If set dates are displayed with a '/' separator and numerics with an embedded ';'.
7 | If set and the field is numeric, it is treated as a signed integer when being output to the screen.

A run-time error (#ERR=85) occurs if:

  • The field type is not A,C, J, or N

  • If starting byte or field length is 0

  • If the display length is greater than 128

  • If a numeric length is greater than 4 (6 for triple precision)

  • If the number of decimal positions is greater than the number of print positions.

If the information is valid, the @SET statement converts and stores the information in a 10 byte portion of the area of memory reserved by a @DIM statement. Typically @SETFD and @SETSD statements are used to set this information. The @SET statement is intended to be used in a parameter driven software environment since this allows the field specs to be read from a file into a string and then the field specs to be set from the string.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

:

: This sample routine reads field specs froma file.

: The first byte in the file contains the number of field specs.

:

5000 OPEN FILE(15,5),"FILE.SPC"                :OPEN PARAMETER FILE

DIM SPEC$(9)

READ FILE(15),NFLDS                       :GET NUMBER OF FIELDS

@DIM FIELDS                               :DIMENSION FIELD SPEC AREA

FOR II%=1 TO NFLDS

READ FILE(15),SPEC$                  :READ FIELD SPECS FROM FILE

@SET I,SPEC$                         :SET FIELD SPEC FOR FIELD I

CLOSE FILE(15)

5090 RETURN


@SETFD

@SETFD ---------- Defines the type, start, length an numeric format of an '@' statement

Type

U/BL Statement.

Syntax

@SETFD field,type,start,length,format

Arguments

field | A numeric expression that specifies the field to be defined.
type | A string variable or literal specifying the type of field. This must be A, C, J or N.
start | A numeric expression that specifies the starting location of the field within the record (relative to 1).
length | A numeric expression that specifies the length of the field in the record. This is the number of bytes.
format | A numeric expression that specifies the format of the numeric field. This is in the form XXy wher XX=number of print positions and Y=number of decimal positons. For example, 102 means that there ae 10 print positons and the decimal point is placed in front of the rightmost 2 digits. if this is not a numeric field, input a character,( that is, a zero) although it will be ignored during the @INPUT, @PRINT, and @FORMAT statements.

Description

The @SETFD statement sets the same information in the field spec are as described in bytes 1-6 of the @SET statement section. The statement is provided because there are times when it is not necessary to specify the screen positions. Additionally the field specs are more easily identified when using the @SETFD statement instead of the @SET statement.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

See the examples in @PRINT and @INPUT.


@SETSD

@SETSD ---------- Defines the type, start, length an numeric format of an '@' statement

Type

U/BL Statement.

Syntax

@SETSD field,line,column,flags

Arguments

field | A numeric expression that specifies the field to be defined.
line | A numeric expression that specifies the line (y coordinate) on the CRT where the field is to be displayed.
column | A numeric expression that specifies the column (x coordinate) on the CRT where the field is to be displayed.
flags | A numeric expression where the low byte is used as the value of a field's flags byte. This is described in the @SET statement section.

Description

The @SETFD statement sets the same information in the field spec are as described in bytes 7-9 of the @SET statement section.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.

Example

See the examples in @PRINT and @INPUT.


$S

$S ------------ Display the contents of the FOR/NEXT and GOSUB/RETURN stacks

Type

U/BL command.

Syntax

$S

Description

The $S command displays the contents of the FOR/NEXT and GOSUB/RETURN stacks.


$SCREEN_INIT

$SCREEN_INIT ----------- Initialize internal screen buffer

Type

U/BL Command and Statement.

Syntax

$SCREEN_INIT error,flag,row1,col1,row2,col2

Argument

error | Numeric variable in which error codes are to be returned.
flag | Numeric expression to indicate which parts of the screen are to be initialised.
row1,col1 | The coordinates of one corner of the rectangle to be initialised.
row2,col2 | The coordinates of the diagonally opposite corner of the rectangle to be initialised.

Description

The $SCREEN_INIT statement clears the part of the internal screen buffer corresponding to the rectangle on the screen where one corner has coordinates row1,col1 and where the diagonally opposite corner has coordinates row2,col2. The $SCREEN_INIT statement doesn't change the screen itself. See the $SCREEN_PAINT statement.

Use $SCREEN_INIT to clear unwanted data from the internal screen buffer. By specifying an area and a flag, you control what information is retained. Use the flag to indicate what part of the internal screen buffer is to be cleared:

flag=0 | Initialises both foreground and background.
flag=1 | Initialises background only.
flag=2 | Initialises foreground only.

Examples

* $SCREEN_INIT ERROR,0,1,1,24,80

Clears the whole internal screen buffer.

* $SCREEN_INIT ERROR,1,1,10,80

Clears the part of the internal screen buffer corresponding to the first ten lines of the foreground.


$SCREEN_LOAD

$SCREEN_LOAD ------------ Load the contents of a string into the internal screen buffer

Type

U/BL command and statement.

Syntax

$SCREEN_LOAD error,screen$

Arguments

error | Numeric variable to receive error codes.
screen$ | A string variable DIMensioned to at least 4000 bytes which contains information to be displayed on the screen.

Description

The $SCREEN_LOAD statement copies information from the string variable into the internal buffer. The string variable must be formatted properly. See $TURN_ON(SCREEN_RECORD) and $SCREEN_STORE for further information.

Use the $SCREEN_LOAD statement to restore to the internal screen buffer screen information that was saved in str$. The actual screen does not change.

Examples

* $SCREEN_LOAD ERROR,B$

Restores B$ into the internal screen buffer.

05000 REM HELP SUBROUTINE

05005 DIM X$[1]

05010 $SCREEN_LOAD ERROR,HELP1$

05020 INPUT @(24,10),"STRIKE ANY KEY TO CONTINUE",@(-10,-1),X$

05030 $SCREEN_LOAD ERROR,HELP2$

05040 INPUT @(24,10),"STRIKE ANY KEY TO CONTINUE",@(-10,-1),X$

05050 $SCREEN_LOAD ERROR,HELP3$

05060 INPUT @(24,10),"STRIKE ANY KEY TO CONTINUE",@(-10,-1),X$

05070 RETURN

This is one way to put up help screens.

See also

$SCREEN_STORE

SLOAD

SSTORE


$SCREEN_PAINT

$SCREEN_PAINT ----------- Displays the contents of the internal screen buffer to the screen

Type

U/BL command and statement.

Syntax

$SCREEN_PAINT error,flag,row1,col1,row2,col2

Arguments

error | Numeric variable to receive error codes.
flag | Numeric expression to control what parts of the screen are to be displayed.
row1,col1 | The coordinates of one corner of the rectangle to be displayed on the screen.
row2,col2 | The coordinates of the diagonally opposite corner of the rectangle to be displayed on the screen.

Description

The $SCREEN_PAINT statement displays the information in the specified part of the internal screen buffer on the screen.

Use the $SCREEN_PAINT statement to display information from the internal screen buffer on the screen or part of the screen. $SCREEN_PAINT can be used to renew the screen after it has been altered, or can be used to display a screen that had been stored earlier. Use the flag to control which screen part is displayed:

flag=0 | Both background and foreground are to be displayed.
flag=1 | Only background is to be displayed.
flag=2 | Only foreground is to be displayed.

Example

* list

00010 $TURN_ON(SCREEN_RECORD)

:

01210 IF ITEM$="H" THEN GOSUB 7600 : HELP

:

07600 REM HELP

07605 STMA 8,5 : FLUSH BUFFER TO ENSURE SCREEN IS CURRENT

07610 $TURN_OFF(SCREEN_RECORD)

:

  {helpful statements}

:

07640 DELAY 5

07670 $SCREEN_PAINT ERROR,0,1,1,24,80

07680 $TURN_ON(SCREEN_RECORD)

07690 RETURN

It is necessary for the SCREEN_RECORD switch to be turned on to capture the current image on the screen. See $TURN_ON(SCREEN_RECORD).


$SCREEN_STORE

$SCREEN_STORE ---------- Stores the internal screen buffer to a string variable

Type

U/BL command and statement.

Syntax

$SCREEN_STORE error, screen$

Arguments

error | Numeric variable to receive error codes.
screen$ | A string variable, DIMensioned to at least 4000 bytes.

Description

The $SCREEN_STORE statement stores the information currently in the internal screen buffer to the screen$ parameter. Bytes 101 to 4000 are reserved for Basic; bytes 1 to 100 are available to the user.

There are two bytes in the internal buffer for every character on the screen. The first is an attribute byte and records if the associated data byte is dim/not dim, underlined/not under lined, blinking/not blinking. There is room for 5 further attributes, for example, reverse video but these will not be added until required. The second byte is the data byte, and contains the ASCII value of the byte displayed in that screen position.

See $TURN_ON(SCREEN_RECORD) for information as to how bytes 101 to 4000 are used.

Use $SCREEN_STORE to save a screen for future sessions, or to make available the internal screen buffer in the current session without losing the information in the internal screen buffer. To ensure the screen is up to date, the output buffer should be flushed with an STMA 8,5 statement before storing a screen.

Examples

* $SCREEN_STORE error, B$

stores the contents of the internal screen buffer into B$.

00020 ON ERR THEN GOSUB 7500 : ERROR

00030 $SCREEN_INIT E,0,1,1,24,80

00040 $TURN_ON(SCREEN_RECORD)

:

07500 REM ERROR

07505 STMA 8,5 : FLUSH OUTPUT BUFFER

07510 $TURN_OFF(SCREEN_RECORD)

07520 $SCREEN_STORE ERROR, B$

07530 GOSUB 8000 : FIXIT

07540 $SCREEN_LOAD ERROR, B$

07550 $SCREEN_PAINT E,0,1,1,24,80

07560 $TURN_ON(SCREEN_RECORD)

07570 RETURN

where FIXIT is some error handling subroutine.

See also

$SCREEN_LOAD

SLOAD

SSTORE


$SET_VALUE

$SET_VALUE -------- Sets system parameters for the user

Type

U/BL statement or command

Syntax

$SET_VALUE(parameter,arg2)

Arguments

parameter | One of the parameters listed below.
arg2 | A string or numeric expression, depending on the parameter to be modified, which contains the value that the parameter is to be set to.

Description

The $SET_VALUE assigns values to system parameters. The $GET_VALUE returns the value of these parameters. The parameters allowed are as follows:

CONSOLE | Sets the value returned by SYS(4) when U/BL runs a background process.
DATE_EDIT | The arg2 parameter is a numeric expression representing the new default for the edit_format parameter received by the $VDATE statement.
DATE_IN | The arg2 parameter is a numeric expression representing the new default for the internal_format parameter of the $DATE$ function and the $VDATE statement
DATE_OUT | The arg2 parameter is a numeric expression representing the new default for the display_format parameter of the $DATE$ function.
LINE_LEN | The arg2 parameter is a numeric expression representing the maximum print line length. The maximum value the line length can be set to is 255.
NL1 | The arg2 parameter is a numeric expression representing the ASCII value of the character which will be treated as a line return. The default value is 10. The line return affects only output with PRINT FILE, and should not be confused with the unpend keys which affect input.
NL2 | The arg2 parameter is a numeric expression representing the ASCII value of the character which will be treated as the optional line return. when it is at its default value of 255 then nothing is printed for NL2.
SCREEN_REFRESH | Sets the screen refresh function key. The default key is Control-F5. The arg2 parameter is the ASCII value of the character following the "<30>" of the two-character function key sequence. If the key specified is pressed, and SCREEN_RECORD is on, and CHAR/FKT is on, the whole screen is refreshed. This feature is used when messages from other processes corrupt the screen, or when hot-keys are used to switch between processes.
U_SCD |
U_USR1 |
U_USR2 |

Example

* list

0010 DIM I$[5]

0020 $SET_VALUE(NL1,65)

0030 $SET_VALUE(NL2,66)

0040 OPEN FILE[1,15],"TESTFILE"

0050 PRINT FILE[1],4

0060 POSITION FILE[1,0]

0070 READ FILE[1],I$

0080 $DISPLAY I$

0090 CLOSE FILE[1]

* run

1 | 32 |
2 | 52 | 4
3 | 65 | A
4 | 66 | B

See also

$GET_VALUE


$SEX

$SEX ----------- Sign extension function

Type

U/BL function

Syntax

var=$SEX(value, bytes)

Arguments

var | A numeric variable
value | A numeric expression, either constant or variable.
bytes | The length of value in bytes. This must be an integer between 1 and 8.

Description

The $SEX function converts a signed integer represented in a small number of bytes (the value argument) into that same signed integer represented in a larger number of bytes (the bytes argument); this is called "sign extension." The bytes argument must be between 1 and 8. Sign extension allows negative numbers to be interpreted as negative numbers. The $SEX function is similar to the $ASX function, except that it takes a numeric expression as an argument.

On the UNIX and Windows platforms, the environment variable BBEXTENSION must include B32 in order to use this statement.

Examples

Some conversions

* let x=$sex(65535,2) : sets x to -1

* let x=$sex(1234,2) : sets x to 1234

* let x=$sex(128,1) : sets x to -128

* let x=$sex(128,2) : sets x to 128

Let's look at the first conversion above in more detail.

00010 DIM NUM$[2]

00020 LET NUM$=CHR$(-1,2)

00030 PRINT ASC(NUM$[1,2]),$SEX(ASC(NUM$[1,2]),2),ASX$(NUM$[1,2])

* run

 65535 -1 -1

Functions that are sometimes used to sign extend integers in Business Basic a:

00121 DEF FNA(X)=OR(X, -AND(X,128)) : one byte

00122 DEF FNB(X)=OR(X, -AND(X,32768)) : two bytes

...

05050 LET A1=FNA(ASC(I$[3,3] \ A2=FNB(ASC(I$[5,6]))

...

The following functions replace the above and execute more quickly:

00121 DEF FNA(X)=$SEX(X,1)

00122 DEF FNB(X)=$SEX(X,2)

See also

$ASX


$SORT

$SORT ---------- Sorts a list of keys in memeory

Type

U/BL command or statement.

Syntax

Format 1: $SORT sd$

Format 2: $SORT error,keys,sd$,sb$,sp$

Arguments

error | Numeric variable to receive error codes.
keys | Numeric expression for the number of keys to be sorted.
sd$ | Sort descriptor string containing information as described below.
sb$ | Sort buffer containing the keys to be sorted.
sp$ | Sort pointer string; must be dimensioned to 4*keys.

Description

This internal sort facility uses the same arguments as Data General's Filesort program, to sort on multiple key fields ascending or descending, but is substantially faster.

The sd$ parameter is made up as follows:

Bytes | Size | Contents
1,1 | 1 | Channel number of file to be sorted.
2,5 | 4 | Number of records to sort.
6,7 | 2 | Record size in bytes.
8,11 | 4 | Byte offset to first record if data file is a subfile.
12,12 | 1 | Set to 1 if deleted records are to be checked for.
13,13 | 1 | Number of key fields in record.
14,18 | 5 | Key field descriptors as follows: Bytes 14,15 First byte of key (1 is first byte of record). Bytes 16,17 Last byte of record. Byte 18 Bit 0=1 Sort field in descending order, else ascending. Bit 1=1 Signed binary field, else unsigned.
19,23 | 5 | Next key field's descriptors

If you set the BBEXTENSION environment variable to B32 (Format 2) then the $SORT command does an in memory sort and has an option to write the sorted data to a file. The sorted pointer string holds pointers to the records of the sort buffer in sorted order at the conclusion of the call. The sort is on ASCII order of characters; it is suitable for sorting character data.

Use the $SORT statement to do memory sorts. Store records in sb$. The sd$ string is formatted as follows:

Bytes | Contents
1,2 | record length
3,4 | key start
5,6 | key finish
7,8 | Order: 0 for ascending, 1 for descending. This flag is only available for the write to channel option; otherwise the array is sorted in ascending order.
9,10 | channel or -1: if this field is not -1 then the sorted contents will be written to the specified channel.

Examples

1. Format 1 - Without BBEXTENSION set to B32.

The following program extracts ten names from a file, sorts them into ascending alphabetical order, and then prints them.

00010 OPEN FILE[0,5],"NAMEFILE"

00020 LET CHAN=0 \ NAMES=10 \ NAMELEN=10 : SET UP CONSTANTS

00030 DIM SD$[24],NAME$[10]

00040 LET SD$[0]=FILL$(0) : INITIALISE SORT DESCRIPTION STRING

00050 LET SD$[1]=CHR$(CHAN,1) \ SD$[2,5]=CHR$(NAMES,4) : CHAN & NORECS

00060 LET SD$[6,7]=CHR$(NAMELEN,2) : RECORD LENGTH

00070 LET SD$[8,11]=CHR$(0,4) : BYTE OFFSET

00080 LET SD$[12,12]=CHR$(0,1) : NO DELETED RECORD CHECKING TO BE DONE

00090 LET SD$[13,13]=CHR$(1,1) : NO OF KEY FIELDS IN RECORD

00100 LET SD$[14,15]=CHR$(1,2) : FIRST BYTE OF KEY (FIRST BYTE OF REC)

00110 LET SD$[16,17]=CHR$(NAMELEN,2) : END OF KEY (FULL LENGTH HERE)

00120 LET SD$[18,18]=CHR$(0,1) : ASCENDING ORDER, UNSIGNED FIELD

00130 $SORT SD$

00140 CLOSE

00150 OPEN FILE[0,5],"NAMEFILE"

00160 FOR I=1 TO NAMES

00170 READ FILE[0],NAME$

00180 PRINT NAME$

00190 NEXT I

00200 CLOSE

2. Format 2 - With BBEXTENSION set to B32.

The following program accepts ten names from the keyboard, sorts them into alphabetical order, and then prints them.

00010 LET NAMES=10 \ NAMELEN=10: SET UP CONSTANTS

00020 DIM SD$[10],SB$[NAMES*NAMELEN],SP$[4*NAMES],NAME$[NAMELEN]

00030 LET SD$[0]=FILL$(0) : INITIALISE SORT DESCRIPTION STRING

00040 LET SD$[1,2]=CHR$(NAMELEN,2) : RECORD LENGTH

00050 LET SD$[3,4]=CHR$(1,2) : START OF KEY WITHIN RECORD

00060 LET SD$[5,6]=CHR$(NAMELEN,2) : END OF KEY (FULL LENGTH HERE)

00070 LET SD$[7,8]=CHR$(0,2) : ASCENDING ORDER

00075 LET SD$[9,10]=CHR$(-1,2) : DON'T OUTPUT TO FILE

00080 FOR I=1 TO NAMES

00090 INPUT NAME$ : GET DATA TO SORT

00100 LET SB$[(I-1)*NAMELEN+1,I*NAMELEN]=NAME$,FILL$(32)

00110 NEXT I

00120 $SORT ERROR,10,SD$,SB$,SP$ : PERFORM SORT

00130 FOR I=1 TO NAMES

00140 LET P=ASC(SP$[I*2-1,I*2]) : GET POINTER TO DATA

00150 LET NAME$=SB$[(P-1)*NAMELEN+1,P*NAMELEN] : GET DATA ITSELF

00160 PRINT NAME$

00170 NEXT I


$STACKS

$STACKS ------------ Display the contents of the FOR/NEXT and GOSUB/RETURN stacks

Type

U/BL command.

Syntax

$STACKS

Description

The $STACKS command displays the contents of the FOR/NEXT and GOSUB/RETURN stacks.

This command is an alias for the $S command.


$STATUS

$STATUS ------------ Display a dump of the U/BL program details

This command is an alias for the $P command.


SAVE

SAVE ---------- Saves a program with its variables

Type

U/BL command and statement.

Syntax

SAVE [program$]

Arguments

program$

A string expression containing the name of the program being SAVEd.

Description

The SAVE statement writes the program in memory but it doesn't retain the contents of its variables, the GOSUB stack or the position reached for a CON statement to resume from, unless the environment variable BBEXTENSION is set to include B32 or the environment variable BBSAVE is set to "Y".

If the environment variable BBEXTN is set, then the specified ".extension" will be appended to the program$ parameter.

If the environment variable BBPROGS is set, the program will always be saved in the first directory specified unless a pathname is used.

If a file with the specified name already exists, the following error message is displayed:

I/O error 9 - File already exists

This error can be trapped with an ON ERR statement. If the program$ parameter is not specified, the current program name is used. This name is set by the last LOAD, RUN "program", SAVE or REPLACE statement and reset by a NEW statement. It defaults to SCRATCH.

If no pathname is specified within the program$ parameter, the program is saved in the current directory. The current program name does not include a pathname.

Example

* load "test

* list

00010 REM This is a test program

00020 PRINT "Hello"

00030 END

* 25 ;"World

* list

00010 REM This is a test program

00020 PRINT "Hello"

00025 PRINT "World"

00030 END

* save "test1

* load "test1

* list

00010 REM This is a test program

00020 PRINT "Hello"

00025 PRINT "World"

00030 END

See also

$IREPLACE

$ISAVE

BBSAVE

REPLACE

REPLACEV

SAVEV


SAVEV

SAVEV ---------- Write the program in memory, along with the contents of its variables

Type

U/BL command and statement.

Syntax

SAVEV [program$]

Arguments

program$

A string expression containing the name of the program being SAVEVd.

Description

The SAVEV command writes the program in memory, along with the contents of its variables, the GOSUB stack, and the position reached in the program for a CON statement to resume from.

If the environment variable BBEXTN is set, then the specified ".extension" will be appended to the program$ argument. If the program$ argument is not specified, the current program name is used. This name is set by the last LOAD, RUN, SAVE or REPLACE statement and defaults to SCRATCH. If no pathname is specified within the program$ argument, the program is saved in the current directory. The current program name does not include a pathname. If the environment variable BBPROGS is set, the program will always be saved in the first directory specified unless a pathname is used.

Note: This functionality is part of the core product,that is, BBEXTENSION does not have to be set to include B32 in order to use it.

To maintain SAVE file compatibility, the SAVEV command does not save more than eight nested levels of FOR/NEXT. This means that you cannot SAVEV a program that is stopped at a place more than eight loop levels deep, and expect it to LOAD and CONtinue. If the program stopped with more than eight entries on the FOR/NEXT stack, the warning message:

"WARNING: Too many FOR/NEXT stacks to save - Truncated to 8 Levels"

is displayed when the program is SAVEVed. If this happens, then the program cannot be LOADed and CONtinued.

Example

* load "test

* list

00010 REM This is a test program

00020 LET X=3 \ Y=4

00030 END

* run

* ;x;y

 3 4

* savev "test1

* new

* ;x;y

 0 0

* load "test1

* ;x;y

 3 4

See also

$IREPLACE

$ISAVE

BBSAVE

REPLACE

REPLACEV

SAVE


SCANUNTIL

SCANUNTIL ----------- Scans a string until one of a set of characters is found

Type

U/BL statement.

Syntax

SCANUNTIL position, scanstring, character_set [,start]

Argument

position | A numeric variable which receives the position of the last character in scanstring which is not in character_set.
scanstring | A string expression to be scanned
character_set | A string expression containing a set of characters to be searched for.
start | A numeric expression indicating the position in scanstring to begin scanning. If not specified scanuntil begins at the start of scanstring.

Description

The SCANUNTIL statement reads through a string, starting at the byte specified, and compares each character to the set of characters supplied, until it finds a match. Unlike the POS and STRPOS statements, the SCANUNTIL statement only checks to see if the string being scanned contains any one of the characters in the set, not the whole character_set string.

The result of SCANUNTIL is returned in the position parameter, and is a number representing the position of the last character read from the string which was not a member of the set. If the end of the string is reached, the position parameter contains the length of the string. If the start specified is greater than the length of the string, the position parameter contains zero.

Example

The following program determines when a line of text changes from upper to lower case text, or vice versa. It is assumed that the line begins with at least one upper case letter; this is not reported.

00010 DIM UPPER$[26],LOWER$[26],TEXT$[80]

00020 LET UPPER$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"

00030 LET LOWER$="abcdefghijklmnopqrstuvwxyz"

00050 INPUT USING "","Enter a line of text ",TEXT$

00070 SCANUNTIL P,TEXT$,LOWER$,P+1

00080 IF P=LEN(TEXT$) THEN END

00090 PRINT "Lower case text found at byte";P+1

00100 SCANUNTIL P,TEXT$,UPPER$,P+1

00105 IF P=LEN(TEXT$) THEN END

00110 PRINT "Upper case text found at byte",P+1

00120 GOTO 00070

* run

Enter a line of text Genius is an INFINITE capacity for taking pains

Lower case text found at byte 2

Upper case text found at byte 14

Lower case text found at byte 23

See also

POS

SCANWHILE

STRPOS


SCANWHILE

SCANWHILE ---------- Scans a string while characters are in a given set

Type

U/BL statement.

Syntax

SCANWHILE position, scanstring, character_set [,start]

Arguments

position | A numeric variable which receives the position of the last character in scanstring which is a member of character_set.
scanstring | A string expression to be scanned
character_set | A string expression containing a set of characters to pass over.
start | A numeric expression indicating the position in scanstring to begin scanning. If not specified scanwhile begins at the start of scanstring.

Description

The SCANWHILE statement reads through a string, starting at the byte specified, and compares each character to the set of characters supplied, until there is no match.

The result of the SCANWHILE statement is returned in the position parameter, and is a number representing the position of the last character read from the string which was a member of the set. If the end of the string is reached, the position parameter contains the length of the string. If the start specified is greater than the length of the string, the position parameter contains zero.

Example

This example program strips any non-numeric characters from a string. It uses both the SCANWHILE and SCANUNTIL statements.

00010 DIM TEXT$[80], NUMERIC$[20], DIGIT$[10]

00020 LET DIGIT$="0123456789"

00030 INPUT "Type an integer...",TEXT$

00035 LET LENTEXT=LEN(TEXT$)

00040 SCANUNTIL P1,TEXT$,DIGIT$,P2+1

00050 IF P1=LENTEXT THEN GOTO 100

00060 SCANWHILE P2,TEXT$,DIGIT$,P1+1

00070 LET NUMERIC$[0]=TEXT$[P1+1,P2]

00080 IF P2<LENTEXT THEN GOTO 00040

00100 IF LEN(NUMERIC$)=0 THEN NUMERIC$=0

00110 PRINT "The number entered was ";NUMERIC$

00120 END

* run

Type an integer...1 year's seeding means 7 years weeding

The number entered was 17

See also

POS

SCANUNTIL

STRPOS


SCREEN_BOX

SCREEN_BOX ---------- Displays a box on the terminal or console

Type

U/BL statement.

Syntax

SCREEN_BOX errcod,flag,row1,col1,row2,col2

Arguments

errcod | A numeric variable into which is returned the screen manager error. If there is no error, it returns a zero
flag | A numeric expression that specifies the type of box to be displayed
row1,col1 | A numeric expression giving the row and column of the upper left corner of the box
row2,col2 | A numeric expression giving the row and column of the lower right corner of the box.

Description

The SCREEN_BOX statement displays a box on the screen. The type of box displayed depends on the value of the flag parameter:

Value of Flag | Type of Box
0 | Single line
1 | Double line
2 | Shaded border (reverse video)

When a box is drawn the space within the box is set to blanks (spaces).

If the value of the flag parameter is not one of the values shown above, it returns an error 80, and the box is not drawn.

If the screen manager is not running when this statement is executed, it returns an error 60 in the errcod variable.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

The following program draws a single line box on the screen. Upper left hand corner is at row 8, column 10 and lower right corner is at row 20, column 50.

10 SCREEN_BOX ERRNO, 0, 8, 10, 20, 50

20 END


SETCOLOR

SETCOLOR ---------- Sets the color of a Windows Object

Type

Windows Object Command.

Syntax

SETCOLOR(ID, FG, COLOR [,STAT])

Arguments

ID | The ID number of the Windows Object.
FG | The value of FG can either be 0 or 1, where: 0 - means "set the background color" 1- means "set the foreground color".
COLOR | This is a variable which indicates the color. (See below for more information.)
STAT | The status variable.

Description

The SETCOLOR statement sets the color of a Windows Object.

The meaning of COLOR is bit-significant, and can be in either one of two formats:

  • RGB

  • SystemColor

The format of an RGB value is as follows:

For example:

bright red | 255 | (0 * 65536) + (0 * 256) + (255 * 1)
dark red | 128 | (0 * 65536) + (0 * 256) + (128 * 1)
bright yellow | 65535 | (0 * 65536) + (255 * 256) + (255 * 1)
orangy yellow | 32896 | (0 * 65536) + (128 * 256) + (128 * 1)
bright purple | 16711935 | (255 * 65536) + (0 * 256) + (255 * 1)

The format of a SystemColor value is as follows:

SysColor Value | Meaning
0 | Scroll bar grey area.
1 | Desktop.
2 | Active window title bar. Windows 98/Me, Windows 2000 or later: Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.
3 | Inactive window caption. Windows 98/Me, Windows 2000 or later: Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.
4 | Menu background.
5 | Window background.
6 | Window frame.
7 | Text in menus.
8 | Text in windows.
9 | Text in caption, size box, and scroll bar arrow box.
10 | Active window border.
11 | Inactive window border.
12 | Background color of multiple document interface (MDI) applications.
13 | Item(s) selected in a control.
14 | Text of item(s) selected in a control.
15 | Face color for three-dimensional display elements and for dialog box backgrounds.
16 | Shadow color for three-dimensional display elements (for edges facing away from the light source).
17 | Greyed (disabled) text. This color is set to 0 if the current display driver does not support a solid grey color.
18 | Text on push buttons.
19 | Color of text in an inactive caption.
20 | Highlight color for three-dimensional display elements (for edges facing the light source.)
21 | Dark shadow for three-dimensional display elements.
22 | Light color for three-dimensional display elements (for edges facing the light source.)
23 | Text color for tooltip controls.
24 | Background color for tooltip controls.
25 | Not used.
26 | Windows 98/Me, Windows 2000 or later: Color for a hot-tracked item. Single clicking a hot-tracked item executes the item.
27 | Windows 98/Me, Windows 2000 or later: Right side color in the color gradient of an active window's title bar.
28 | Windows 98/Me, Windows 2000 or later: Right side color in the color gradient of an inactive window's title bar.

For example:

Color of text in an inactive caption | 1073741843 | 2^30 + 19
Color of Desktop | 1073741825 | 2^30 + 1

Note: 1073741824 is 2^30

The System Color values are the ones currently in use on the machine on which U/Gi is running (not, for example, those on the machine on which U/BL is running or on which the U/BL program was compiled).


SETCOM1

SETCOM1 ---------- Sets interprogram communication code 1

Type

U/BL statement.

Syntax

SETCOM1 value

Arguments

value

A two-byte numeric expression that is moved to the proper field.

Description

The SETCOM1 statement moves the value of communication code 1 into the proper field.

Communication code 1 is a two-byte inter-program communication code, usually used as flags when executing a SWAP or CHAIN between programs.

The SETCOM1 statement is equivalent to the STMA 2,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for GETCOM1.


SETCOM2

SETCOM2 ---------- Sets interprogram communication code 2

Type

U/BL statement.

Syntax

SETCOM2 value

Arguments

value

A two-byte numeric expression that is moved to the proper field.

Description

The SETCOM2 statement moves the value of communication code 2 into the proper field.

Communication code 2 is a two-byte inter-program communication code, usually used as flags when executing a SWAP or CHAIN between programs.

The SETCOM2 statement is equivalent to the STMA 2,2 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for GETCOM2.


SETCOM3

SETCOM3 ---------- Sets interprogram communication code 3

Type

U/BL statement.

Syntax

SETCOM3 value

Arguments

value

A two-byte numeric expression that is moved to the proper field.

Description

The SETCOM3 statement moves the value of communication code 3 into the proper field. Communication code 3 is a two-byte inter-program communication code, usually used as flags when executing a SWAP or CHAIN between programs.

The SETCOM3 statement is equivalent to the STMA 2,3 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for GETCOM3.


SETCRAM

SETCRAM ---------- Sets the four special cram characters

Type

U/BL statement.

Syntax

SETCRAM cram string

Arguments

cram string

A string variable or literal containing the four special cram characters.

Description

The SETCRAM statement sets the four special cram characters to the characters in the cram string.

The cram function (see CRM$) converts ASCII text characters into radix 40 representation. This allows you to cram 4-byte characters into the space normally occupied by 2 bytes.

You can only use 40 unique characters; the CRM$ function allows the 26 letters of the alphabet and the 10 ASCII digits. This leaves 4 other characters, with the BASIC defaults being the space ' ', slash '/', comma ',', and period '.' characters, in that order.

You can use SETCRAM to change the BASIC cram characters for the current task. If you use SETCRAM , remember that the order of the four special cram characters is important. The SETCRAM statement is equivalent to the STMA 10,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for STMA 10.


SETDELKEY

SETDELKEY ---------- Sets the decimal value of the key that causes the backspace sequence to be sent

Type

U/BL statement.

Syntax

SETDELKEY value

Arguments

value

A numeric expression into which the new value of the key is sent.

Description

The SETDELKEY statement sets the new decimal value of the key that causes the backspace sequence. The default value is 8. It is equivalent to the STMA 4,3 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 4,3.


SETECHOFF

SETECHOFF ---------- SETs the terminal control flag for character echo to 1

Type

U/BL statement.

Syntax

SETECHOFF

Description

The SETECHOFF statement SETS the value of the ECHO flag to 1. When the flag is set to 1, characters are not echoed to the port when they are received by U/BL. It is equivalent to the STMA 6,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


SETECHON

SETECHON ---------- RESETs the terminal control flag for character echo to 0

Type

U/BL statement.

Syntax

SETECHON

Description

The SETECHON statement RESETs the value of the ECHO flag to 0. When the flag is set to 0, characters are echoed to the port when they are received by U/BL. It is equivalent to the STMA 7,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


SETFILLC

SETFILLC ---------- SETs the terminal control flag for fill characters to 1

Type

U/BL statement.

Syntax

SETFILLC

Description

The SETFILLC statement SETs the value of the FILL flag to 1. When the flag is set to 1, PRINT USING type D, E or F field mask characters to the left of the significant digit are replaced by the character.

The default fill character (blank) always replaces mask character to the left of the first significant digit, even if SETFILLC is in effect.

Note: SWAP saves a value, and unSWAP restores a value. Therefore, if the swapped-to program changes this value, it is restored to its prior value when the swapped-to program ENDs.

If the fill character is blank, the mask character is always overwritten, even if NOFILLC (STMA 7,7) is in effect.

SETFILLC is equivalent to STMA 6,7.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


SETFOCUS

SETFOCUS ---------- Sets the keyboard focus to a particular Windows object

Type

Windows Object Command

Syntax

SETFOCUS(ID, [, STAT])

Arguments

ID | The unique handle of the Windows object
STAT | Optional status return

Description

The SETFOCUS command sets the keyboard focus to a particular Windows object. In Windows, there is a concept of a currently active Windows object that is said to have the focus or keyboard focus. This is often shown by the presence of a dotted rectangle around the object, and indicates that the object can be activated by the keyboard. For example, if the focus is on an edit box, characters typed will change the text being edited. If the focus is on a check box, pressing space turns that object on or off.

It is important to remember that the main panel must have the focus for ordinary text entry. After entry from a set of Windows objects, enter:

SETFOCUS(-1, ER)

to return the focus to the current U/BL window, or the U/BL base panel if no window is visible.

If using the SETFOCUS command to change the focus from a Windows Object with a KILLFOCUS message generator, a KILLFOCUS message is generated by default. To prevent this, use the SETGUIOPT 32 statement.

Applies To

All Windows objects with a handle.

Example

REM *** Create the edit boxes ****

EDITBOX(1,5,5,1,40,"Name",0)

EDITBOX(2,7,5,1,40,"Address 1",0)

EDITBOX(3,8,5,1,40,"Address 2",0)

REM *** Start on the first address line

SETFOCUS(2)

See Also

BUTTON

COMBOBOX

EDITBOX

ENABLEWO

LISTBOX

RADIOBUTTON

SHOWWO

TEXTBOX


SETGUIOPT

SETGUIOPT ---------- Sets options for the U/Gi and the Windows objects

Type

Windows Object Command

Syntax

SETGUIOPT(OPTION, SETTING$ [, STAT])

Arguments

OPTION | The option number as detailed below
SETTING$ | A string whose meaning varies with the option number
STAT | Optional status return

Description

The SETGUIOPT statement allows a BBASIC program to manipulate U/Gi's configuration. It can perform many different functions depending on the setting of the OPTION parameter:

0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29
30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39
40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49
50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 |  |

Refer to the table below for the individual functionality for each possible value of the OPTION parameter. The values of the SETTING$ parameter varies from SETGUIOPT function to function; the values for each one are also outlined in the table below.

Option

Description

0

Sets the color of U/Gi's basepanel with SETTING$ holding the chosen color in the format "<r> <g> <b>" , where <r>, <g> and <b> are numbers which specify the intensities (in the range 0 - 255) of the primary colors (red, green and blue). For example, the string "255 0 0" represents red, "192 192 192" represents light gray.

1

Enables or disables U/Gi's 'pseudo-proportional' mode. Refer to the U/Gi Universal Graphical Interface Rev 4.XX Release Notes for a full explanation of this mode and before using proportional fonts. SETTING$ holds "TRUE" or "FALSE" as appropriate.

2

This setting is no longer supported.

3

Sets the color of U/Gi's hotspots, with SETTING$ holding the chosen color in the format "<r> <g> <b>" where <r>; <g> and <b> are numbers which specify the intensities (in the range 0 - 255) of the primary colors (red; green and blue). For example, the string "255 0 0" represents red, "192 192 192" represents light gray. Changing this color while hotspots are displayed will not redraw those regions, however if they are later re-drawn (perhaps because a window has been displayed over them and later hidden) they will be drawn in the current hotspot color at that time, rather than the color they were originally created in.

4

Selects the justification used when displaying text on a hotspot (SETTING$ contains "LEFT"; "RIGHT" or "CENTRE"). Changing the justification while hotspots are displayed does not redraw those regions, however if they are later re-drawn (perhaps because a window has been displayed over them and later hidden) they will be drawn using the current justification at that time, rather than the original setting.

5

Sets the string to be sent following a message from a Windows object. This enables the object to unpend existing INPUT statements.

6

This option is no longer supported.

7

Sets the Windows objects' font. The SETTING$ parameter must be set to the font and point-size to be used, for example, "arial/10". U/Gi can remember and display the last five fonts used.

8

Selects the set of menus displayed as U/Gi's menu bar. Use a value for SETTING$ of "SYSTEM" to use the default menus or "USER" to employ a user-defined (by the ADDMENU statement) set

9

Sets (to the contents of SETTING$) the title displayed on U/Gi's window

10

Selects whether the Windows objects are displayed as 3D controls. By default this mode is OFF. Calling this function with SETTING$ set to "ON" enables it. Calling this function with SETTING$ set to "AUTO" enables 3D mode and automatically changes the color scheme to allow 3D controls to appear correctly.See Creating 3D look Windows Objects.

11

Sets the size, in pixels, of the U/Gi window. The SETTING$ parameter holds "<x>,<y>,<o>" , where <x> is the horizontal size, and <y> is the vertical size.The <o> field specifies the sizing option to be selected. It can be set to the following values:

1 | Do not resize the font
2 | Prevent the window from being re-sized by the mouse.

If <x> is -1, only the option is applied, and the window is not re-sized.

12

Specifies a bitmap to display on the current window. If the bitmap name is preceded by an exclamation mark (!), a single copy of the bitmap will be centred in the window, otherwise the bitmap will be used to 'tile' the screen. If SETTING$ is set to "" any existing bitmap will be removed. If using U/Gi 3.XX when specifying the pathname of the bitmap, only the short name version (MS/DOS 8+3 format) of the bitmaps path must be used. For example, do not use the path C:\WIN95\Program Files\APP\BITMAP.BMP but use C:\WIN95\PROGRA~1\APP\BITMAP.BMP instead. This restriction does not apply to U/Gi 4.

13

Selects which method is used to activate keyboard shortcuts for the Windows Objects. This SETGUIOPT statement does not effect the shortcut mode of the U/Gi menu bars which always require an ALT key to action them from the keyboard.A SETTING$ of "NONE" means that no shortcut is available (this is the default setting); "ALT" means that the <ALT> key must be pressed in combination with the accelerator key and "PLAIN" means that the key alone activates the button. Use the PLAIN mode only in exceptional circumstances. It slows the system, and prevents full data entry in the main plain.

14

Sets the scaling factors for Windows objects' co-ordinate systems. These values (one each for horizontal and vertical directions) are used as a scalar for the co-ordinates and sizes of the Windows objects. SETTING$ is initialized to "<x>,<y>" where <x> is the horizontal and <y> the vertical scaling factor. When objects are defined, the row and column locations and the horizontal and vertical sizes, are divided by the appropriate scalar to determine the actual size of the object. By default, the scalar for each direction is 1, hence all the objects are created exactly as the specified size. If values other than 1 are specified, the sizes and locations specified in the object creation statement are divided by the scalar - effectively treating the specified sizes/locations as fractions of character cells. For example, if a SETGUIOPT(14,"3,4") is made, the horizontal parameters on an object creation statement is regarded as being in thirds of a character cell; the vertical ones as being in quarters. Owing to display limitations (particularly on low resolution displays), Transoft does not recommend scaling the object sizes by more than 12 (do not use smaller units than twelfths of a character cell).

15

Enables double-clicks on the main panel to return numeric data from the back plane. Dependant on the operation mode of this feature, U/Gi can, from a double click on the background panel, determine what number the user was attempting to select and return that to U/BL's input stream. The data is sent, followed by a termination character (usually the unpend character). SETTING$ specifies both the operation mode of this feature and the termination character to use. This is done via two comma separated numbers the first specifying the mode of auto-selection to be used:

0 | No automatic selection
1 | Only numbers that are double-clicked will be selected
2 | Those numbers immediately preceding the double click on the screen are selected. This will look back along the line for the number, but will stop looking when it meets a space.
3 | As option 2, but the search will only stop if more than 1 consecutive space is detected.
4 | The selection logic looks back along the whole of the current line.

In all cases (where the selection logic is enabled), the number returned is the first uninterrupted group of digits encountered which precede the double-click (or in the case of mode 1 are directly double-clicked).The second parameter in SETTING$ is the ASCII value of the unpend character to be sent along with the selected number. For example, a SETGUIOPT(15,"3,10") will look back from a double-click until it finds either a number or more than one consecutive space. If a number is found, this will be put into U/BL's input buffer followed by an ASCII 10 (newline).

16

Specifies how U/Gi copes with the WMAKE style flags. Under previous versions of U/Gi when running with
U/BL (and UBB) in GUI (-g) mode, windows created by a WMAKE statement were always displayed with captions and borders regardless of the style flags used on the WMAKE statement (which could request that no border or caption be displayed). This kept the display in line with a Windows appearance. However, for screens sized exactly to the dimensions of the Windows without title bars, this poses problems. To combat this, U/Gi 3.XX and above allows the user to select the behavior they would prefer. The options are selected via the SETTING$ parameter (for example, SETGUIOPT (16, "3") ) and the available options are:

0 | The default. As in earlier versions of U/Gi, all windows are displayed with a title bar regardless of the WMAKE style flag.
1 | All Windows are created exactly as specified by the STYLE option of the WMAKE statement
2 | All Windows except with those with a STYLE of 0 are created with captions and borders.
3 | As the default option, but extra space is added to the window to cope with "falling off", where the title causes visible lines to disappear.

A change in the SETGUIOPT 16 setting will only be reflected if a window is deleted and re-created.

17

Changes the colors used to display one of the 16 combinations of the Business BASIC character attributes. SETTING$ is primed to contain "<ac>, <fg>, <bg>, <flg>" where <ac> indicates the combination of BBASIC attributes being changed:

0 | Plain text
1 | Blink
2 | Underline
3 | Bold
4 | Blink & underline
5 | Blink & bold
6 | Underline & bold
7 | Blink, underline & bold
8 | Inverse
9 | Inverse & blink
10 | Inverse & underline
11 | Inverse & bold
12 | Inverse, blink & underline
13 | Inverse, blink & bold
14 | Inverse, underline & bold
15 | Inverse, blink, underline & bold

<fg> and <bg> specify the foreground and background colors to use (the color's number on U/Gi's palette. See the 'Custom Colors' dialog accessed from the 'Preferences/Colors/Customise' menu) and <flg> is a bitmask specifying which Windows attributes should be used:

2 | Bold
4 | Underlined
8 | Italic

or (if <flg> is an odd number) that U/Gi should re-draw the screen after changing the attribute setting (for performance reasons, only re-draw after making the last in a series of changes). For example, SETGUIOPT(17, "14, 4, 1, 7") will cause U/Gi to display all characters with the BBASIC inverse; underline and bold attributes on, using the fourth color on U/Gi's palette as the foreground color, the second color on the palette as the background and will use the Windows bold and underlined attributes as well. When this statement is run, U/Gi will also re-draw the screen to reflect the changes.

18

Changes one of the colors in U/Gi's current palette. SETTING$ holds: "<i>,<r> <g> <b>,<f>" where:

  • <i> is the index to the color in U/Gi's color palette (a number between 0 and 15 which corresponds to the colors listed on U/Gi's 'Custom Colors' dialog accessed from the 'Preferences/Colors/Customise' menu);

  • <r>; <g> and <b> specify the intensities (in the range 0 - 255) of the primary colors (red; green and blue)

  • <f> is an optional flag (if 1, U/Gi will re-draw the screen - only use this with the last color change if you are changing more than one).

For example, SETGUIOPT(18, "0, 255 0 0,1") will change U/Gi color 0 to red and redraw the screen so that the changes become visible.

19

Specifies whether U/Gi will terminate if running connected to a U/BL Windows 95/98 or Windows NT task which BYEs off (or is terminated from UBLMON).

SETGUIOPT (19,”0”) is the default. If the U/BL process BYEs off or is terminated this has no effect on the U/Gi process.

SETGUIOPT (19,”1”) specifies that U/Gi will terminate if it is connected to a Windows U/BL process that BYEs off or is terminated from UBLMON

SETGUIOPT (19,”2”) disables the U/Gi close gadget and the Fil/Exit menu option so that the only means of terminating U/Gi (and the U/BL session running within it) is for the U/BL process to BYE off or be terminated from UBLMON. In this case ALT-F4 will allow U/Gi termination but will display a warning.

20

Sets the styles and colors used for drawing boxes. All the values for SETTING$ follow the U/Gi dialog box for configuring the box settings - the options are:

  • "0, <r> <g> <b>" – Set background color

  • "1, <r> <g> <b>" – Set highlight color"

  • 2, <r> <g> <b>" – Set lowlight color

where <r>, <g> and <b> specify the relative intensities (in the range 0-255) of red, green and blue making up the actual color. In addition, two other options can be set:

  • "3, <m>" - Set style, where <m> is a number between 0 and 3 specifying the type of box characters (thin; thick; recessed or raised) to be used

  • "4" – Redraw all boxes which causes all the boxes on the screen to be re-drawn using the new settings.

21

Selects which of U/Gi's control bars (the scroll; tool and status bars) are displayed. The format of SETTING$ is:

"<bar>, <state>"

where <bar> is a number identifying the bar being controlled (0 – Scroll Bar, 1 - Toolbars, 2 – Status Bar) and <state> specifies whether the bar is to be made visible (<state> of 1) or to be switched off (<state> of 0). Under U/Gi 4 multiple toolbars are supported. Function 21 simultaneously controls all of the toolbars under U/Gi 4. To control an individual toolbar, use SETGUIOPT function 50 (see below).

22

Selects whether or not the Windows cursor is displayed as the standard pointer (a SETTING$ of "-1") or a wait cursor (a SETTING$ of "1") while U/Gi is the focused application. When using other applications with U/Gi, these can sometimes change the state of the cursor. To prevent this from having a permanent effect, periodically call this function with a SETTING$ of 0 as this refreshes the state of the cursor.

23

Specifies whether the U/Gi main window is displayed center justified within a bordered area of the U/Gi frame or occupies the entire area of the U/Gi frame:

SETGUIOPT(23,"1",stat) - Window is displayed centered within a border

SETGUIOPT(23,"2",stat) - Window occupies the entire U/Gi frame.

24

Specifies which U/BL window (as created by WMAKE) new Windows Objects will be created in. This enables windows to be built up before they are shown. Set the value to "" to return Windows object creation to the current window. For example:

WMAKE("MYWND",5,5,10,10,0)

SETGUIOPT(24,"MYWND")

BUTTON(1, ....)

EDITBOX(2, ...)

WSHOW("MYWND")

REM ** Go back to the current window

SETGUIOPT(24,"")

To set the 'creation focus' to U/Gi's basepanel (the U/Gi background) call this function with SETTING$="TSEMULATOR

25

Specifies the U/BL window in which new text will be placed. See SETGUIOPT function 24 above for details.

26

Specifies which button will be activated when the RETURN key is pressed. If n is set to –1, then pressing RETURN acts as if the button with the current focus has been pressed. If n is set to the number of a button then pressing RETURN acts as if that button was clicked wherever the focus currently is. The button must exist and not be disabled for this to occur. If n is zero then the above effects are turned off.

27

Provides the ability to disable menus that have been created via the ADDMENU command. The SETTING$ parameter takes a value of:"<m>,<i>,<s>,<n>") where:

  • <m> is the menu number

  • <i> is the item number

  • <s> is the sub-item number as defined when creating the menu item.

  • <n> defines the state of the item – bit 1 sets disabled/enabled, bit 2 sets unchecked/checked. For example:

0 = disabled + unchecked
1 = enabled + unchecked
2 = disabled +checked
3 = enabled +checked.

(Checked means that a check (tick) mark is displayed to the left of the menu's legend.)

28

This can be used to specify the background color (specified as space separated R,G,B values from 0-255) of the current window, for example:

00010 WMAKE "TEST",5,5,10,20,10

00020 WSHOW "TEST"

00030 SETGUIOPT(28,"255 0 0")

00040 DELAY 10

00050 SETGUIOPT(28,"0 255 0")

00060 DELAY 10

00070 SETGUIOPT(28,"0 0 255")

00080 DELAY 100

00090 WHIDE "TEST"

00100 WDELETE "TEST"

When using U/Gi 4's ability to draw U/BL windows with the appearance of Windows dialogs (see SETGUIOPT function 35) this function will over-ride the default coloration of the U/BL window. However, when the Windows appearance is not in use, printing text to the window will not retain the background color (it will use the usual attributes).

29

Specifies the U/BL window in which boxes as created by the BOX statement are placed. See SETGUIOPT function 24 above for details.

30

SETGUIOPT 30 allows the auto-sizing of Windows Objects. This affects how the size in SETGUIOPT(7) calls to set the font are interpreted. The second value is a string whose numeric value must be a combination of the following values:

1

Font size is interpreted as being tenths of the average character cell height. Thus in this mode, a font Courier/10 will be sized to the same height as a character cell on the back panel. Specifying 5 will result in a font half the height of a character cell.

2

Scale horizontal size with the vertical size. This may or may not be cosmetically appealing depending on the fonts today.

4

Adjust heights of Windows Objects so a cosmetically appealing vertical space is left between them when they share a character boundary. For example, SETGUIOPT(30,"5") turns on 1 and 4.

Setting SETGUIOPT(30,"0") turns off this functionality. The SETGUIOPT 30 must be specified before any SETGUIOPT 7 statements to set the font.

Note: TEXTBOXes are independent of this flag; they have their own flag which achieves this. See the TEXTBOX statement.

31

Specifies whether an Active X control is used in design or user mode. Use zero to set to design mode. Use '1' to set to user mode. The default is 'design' mode. With most Active X controls this will have no effect.

32

SETGUIOPT(32,"1") will suppress a KILLFOCUS message being generated by an explicit SETFOCUS statement.

33

Using the SETGUIOPT(33, "<filename>") statement (where filename is the pathname of the toolbar configuration file that you want U/Gi to use) allows you to control the U/Gi toolbar from a U/BL program.

For example:

SETGUIOPT (33,"/usr/ubl/toolbars.ugi")

34

The SETGUIOPT(34, "<filename>") statement (where filename is the pathname of the button bar configuration file, you want U/Gi to use)allows you to control the U/Gi Window Button bar from a U/BL program. For example:

SETGUIOPT (34,"/usr/ubl/buttbars.ugi")

35

Using the SETGUIOPT(35) statement allows you to create U/BL Windows with the appearance of Windows dialogs. You can choose the style of U/BL Windows with the option to select between the Windows 3.11 style, or the Windows 95/NT style.

The format of the SETTING$ parameter is:

SETGUIOPT(35,"<STYLE>, SHOWCLOSE CLOSESTRING SHOWHELP HELPSTRING SHOWMIN MINSTR SHOWMAX MAXSTR ENABLEUGICLOSE UGICLOSESTRING" [,STAT])

where:

STYLE | The Windows style you wish to use. Either: 0: Windows 3.11 1: Windows 95/98/NT/2000 16: Remap the background color for U/BL windows to that specified in your Windows system settings.
The following options only apply if you specify the Windows window style, otherwise they are ignored.
SHOWCLOSE | Display the Close title bar button. Set to 0 to hide, or 1 to display.
CLOSESTRING | The key or menu item to return when the close button is clicked.
SHOWHELP | Display the Help title bar button. Set to 0 to hide, or 1 to display.
HELPSTRING | The key or menu item to return when the Help button is clicked.
SHOWMIN | Display the Min title bar button. Set to 0 to hide, or 1 to display.
MINSTR | The key or menu item to return when the Min button is clicked.
SHOWMAX | Display the Max title bar button. Set to 0 to hide, or 1 to display.
MAXSTR | The key or menu item to return when the Max button is clicked.
ENABLEUGICLOSE | Enable the U/Gi close button. Set to 0 to disable, or 1 to enable.
UGICLOSESTRING | The key or menu item to return when the U/Gi close button is clicked.

Note: The settings modified by the SETGUIOPT statement only take effect when you create a new window. Existing U/BL windows are not modified.

See the BUTTON statement for the syntax for activating buttons.

36

Unsupported

37

Unsupported

Options 38--45 control U/Gi's printer settings.

38

This statement specifies the font to be printed. Note this is purely the font name, as the size is calculated from the number of rows and columns. Set the SETTING$ parameter to the font you wish to use. For example:

SETGUIOPT(38,"Arial")

sets the font to Arial.

39

This statement specifies the header for the print passthrough. This consists of any string, which may be embedded with the following specially defined sequences:

%% Percentage sign
%p Current Page Number
%c Total Number of pages
%t Time (in local format)
%d Date (in local format)
%u Underline the header/footer text
%b Display the header/footer text in BOLD.
%i Display the header/footer text in italics.
%jl The header/footer text will be LEFT justified.
%jr The header/footer text will be RIGHT justified.
%jc The header/footer text will be CENTER justified.

Set the SETTING$ parameter to the header you wish to use. For example:

SETGUIOPT(39,"Page %p of %c")

40

This statement is used to specify a footer. Footers use the same formatting sequences as headers (see above). Set the SETTING$ parameter to the footer you wish to use. For example:

SETGUIOPT(40,"Copyright Transoft Ltd. %d")

41

The SETGUIOPT 41 function SETGUIOPT (41, ROWS$[, STAT]) allows a U/BL program to select the number of rows U/Gi will display on one page of the printout. For example:

SETGUIOPT(41, "66") : Printout at 66 rows per page

42

The SETGUIOPT 42 function SETGUIOPT (42, COLS$[, STAT]) allows a U/BL program to select the number of characters U/Gi will display on one row of the printout. For example:

SETGUIOPT(42, "80") : Printout at 80 chars per row

43

For printers that support both portrait and landscape layout of the printed page, U/Gi allows you to select the printout's orientation. From a U/BL program this is achieved via function 43 of the SETGUIOPT statement:

SETGUIOPT (43, ORIENT$[, STAT])

The default orientation is portrait (ORIENT$="0") with landscape mode being the option (ORIENT$="1"). For example:

SETGUIOPT(43, "0") : Printout in portrait mode

44

Function 44 of the SETGUIOPT statement allows you to select either of U/Gi's two modes for proportional font support from a U/BL program:

SETGUIOPT (44, PROP$[, STAT])

The default mode is to not use proportional spacing (PROP$="0") with the alternative being to employ it (PROP$="1"). For example:

SETGUIOPT(44, "1") : Use proportional spacing

45

Reserved

Options 46-49 control U/Gi's print-pass-through settings.

46

Function 46 of the SETGUIOPT statement allows you to select the destination of print passthrough output:

SETGUIOPT (46, PPTDEST$[, STAT])

where PPDEST$ can be set to the following values:

0 - Direct to LPT1 on the client PC
1 - Windows Printer Escapes
2 - Windows Printer System
3 - Disable print passthrough

The most flexible option is to employ the Windows printer system, as this allows for an optional print preview option (see below) along with direct control of the character resolution of the printout. For example:

SETGUIOPT(46, "3") : Send PPT to Windows print system

47

When using the Windows print system to output print passthrough, you can request U/Gi to display a preview of the printed output before submitting the document to be printed. This functionality can be controlled from a U/BL program using function 47 of the SETGUIOPT statement:

SETGUIOPT (47, PREVIEW$[, STAT])

The default mode is not to preview the output (PREVIEW$="0") but this can be changed by calling the SETGUIOPT with PREVIEW$="1". For example:

SETGUIOPT(47, "1") : Preview passthrough prints

The preview of the printout is always made when the U/BL job has finished submitting the passthrough output. While the preview is being viewed, U/BL processing will continue but as U/Gi's display is given over to the preview, the standard U/Gi screen will not be visible.

48

Function 48 of the SETGUIOPT statements allows you to control how a previewed document is printed. It also allows U/Gi to optionally display the 'Printer Options' dialog when the preview is closed:

SETGUIOPT(48,ALTER$[, STAT])

This allows the user to alter any of the printer configurations and re-preview the output using the new settings. If the SETGUIOPT statement is called with ALTER$="1", display of the dialog box is enabled, and if it is called with the default ALTER$="0", the dialog box will not be displayed when the user closes the print preview (in this case the previewed output will be immediately rejected). For example:

SETGUIOPT(48, "1") : Allow option change in preview

49

Function 49 of the SETGUIOPT statement allows you to configure U/Gi to delete the contents of the passthrough buffer if the user cancels out of the print preview:

SETGUIOPT(49, CLR_BUF$[, STAT])

If the SETGUIOPT statement is called with CLR_BUF$="1", the print passthrough buffer will be cleared if the user closes the print preview without printing. Calling the statement with CLR_BUF$="0" restores the default functionality of maintaining the contents of the buffer despite the user canceling the print request. For example:

SETGUIOPT(49, "1") : Clear PPT buffer on rejecting

50

Function 50 of the SETGUIOPT statement can be used to show or hide a specific toolbar, or to turn individual toolbars on or off.

The SETTING$ parameter consists of "<toolbar name>,<state>", where

<toolbar name> is the non case-sensitive name of the toolbar

<state> is set to 1 to show the toolbar, or set to 0 to hide the toolbar.

For example:

SETGUIOPT(50,"Main toolbar,1") turns on the main toolbar.

SETGUIOPT(50,"Main toolbar,0") turns the main toolbar off.

51

Using function 50 of the SETGUIOPT statement allows text strings to be passed between U/BL and the Windows Objects supported by U/Gi to be translated according to the TDF, in either direction. The direction is described as:

Outgoing - When strings are being passed from U/BL to U/Gi

Incoming - When strings are being passed from U/Gi to U/BL

The SETTING$ parameter consists of zero or more settings, separated by commas. Each setting is of the form "<option>=<value>", where

<option> is either TDFOUT or TDFIN

<value> is either Y or N.

For example:

SETGUIOPT(51,"TDFIN = N,TDFOut=Y")

Causes TDF-translation to happen on output but not on input;

SETGUIOPT(51,"TDFOUT=N")

Turns outgoing translation off, but leaves incoming translation as it was before.

52

Function 52 of the SETGUIOPT statement allows you to set the Default Window title (as specified on the U/BL Window Styles tab form U/Gi's Preferences/Options menu) from a BBASIC programme. The syntax of the command is:

SETGUIOPT (52,WNAME$,ER).

53

Function 53 of the SETGUIOPT statement allows text highlighting (selection) to be turned off/on in the window in which Windows Objects will currently be created (See SETGUIOPT 24).

SETGUIOPT(53,"1") turns text highlighting ON, and SETGUIOPT(53,"0") turns it OFF. By default in U/GI highlighting is turned on.

For example:

WMAKE("MYWND",5,5,10,10,0)

SETGUIOPT(24,"MYWND")

BUTTON(1, ....)

EDITBOX(2, ...)

WSHOW("MYWND")

SETGUIOPT(53,"0")

REM ** Go back to the current window

SETGUIOPT(24,"")

would turn off the text selection in MYWND.

54

SETGUIOPT 54,"<x>,<y>"

Function 54 of the SETGUIOPT statement is used by the U/BL Studio Forms Designer when WYSIWYG mode has been specified, and forces the size of each character cell to be <x> pixels wide by <y> pixels high. Once this command has been invoked the size of U/GI characters and windows objects cannot be resized.

To revert back to resizable mode the command:

SETGUIOPT(54,"0,0")

must be issued. This command would normally only be used in code generated by the U/BL Studio Forms Designer.

55

SETGUIOPT 55,"<n>"

Function 55 of the SETGUIOPT statement is used by the U/BL Studio Forms Designer when WYSIWYG mode has been invoked to force the windows object font to be created to the exact size specified by the SETGUIOPT 7 statement.

This feature is turned on by setting <n> = 1 and turned off by setting <n> = 2 .

This command would normally only be used in code generated by the U/BL Studio Forms Designer.

56

Setting function 56 of the SETGUIOPT statement to '1' will suppress any killfocus events set on a Windows Object, from being generated when pressing the Close gadget on a window. A program may not want any validation routines triggered by a killfocus to be run if the user is 'closing' the window.

The U/BL Studio Forms Designer sets this option by default. The value can be changed with the Suppress Killfocus on form close check box on the Form Type property page of the Form properties property sheet.

For example:

SETGUIOPT 56,"1"

57

Specifies that the tab stops in LISTBOXes will be modified when the U/Gi window is re-sized.

For example, SETGUIOPT (57, "1") turns this functionality on. By default, it is switched off.

The example program below demonstrates how the tabs should stay in the same relative positions to other listbox text when the UGI size is changed:

WINIT

SETGUIOPT(57,"1")

SETGUIOPT(30,"3")

SETGUIOPT(7,"Courier New/10")

PRINT @(2,10);"A234567890B234567890C23456789"

LISTBOX(1,3,10,2,50,"",1+512)

LISTBOX(2,5,10,3,50,"123456789012345678901234567890",1)

SETTEXT(1,"5,5,5,5,5,5",STAT)

ADDITEM(1,-1,"1<9>2<9>3<9>4<9>5<9>6")

Applies To

  • The U/Gi menu

  • Status, tool, title and scroll bars

  • The U/Gi window (including size; color and appearance)

  • U/Gi's Print passthrough functionality

  • The Windows' cursor; hotspots

  • All Windows objects

  • The BUSINESS BASIC character attributes and the WMAKE and BOX statements.

Example

The example program below uses SETGUIOPT(12), which enables you to specify a bitmap as a background for your window:

REM Storage for filename

DIM A$[255]

REM Use FILEBROWSE to put up an open file dialog

LET OPEN_DIALOG=1 \ OK=1

FILEBROWSE(A$,"BMP",OPEN_DIALOG)

REM Check the button pressed on the file browser

IF OPEN_DIALOG=OK

REM A file was selected, make that the background bitmap

SETGUIOPT(12, A$)

ELSE

REM No file was selected, remove any existing bitmap

SETGUIOPT(12, "")

END IF

See Also

ADDMENU

BUTTON

COMBOBOX

EDITBOX

getguiopt

HOTSPOT

LISTBOX

RADIOBUTTON

STATUSMESSAGE


SETHELP

SETHELP ---------- Enables a custom help file to be used instead of U/Gi Help

Type

Windows Object Command

Syntax

SETHELP(HELPFILENAME$, CONTEXT)

Arguments

HELPFILENAME$ | The path to the help file
CONTEXT | The help context id to be used

Description

This command configures the help displayed when either selecting U/Gi's Help option on the main menu, or pressing the Windows help key, SHIFT-F1. The file name specified in HELPFILENAME$ should be the path and filename of a Windows help file '.HLP' on the client PC (the machine running U/Gi). Under U/Gi 3.10 when specifying this pathname you must only use the short name version (MS/DOS 8+3 format). For example, use:

C:\WIN95\PROGRA~1\APP\HELPTEXT.HLP

instead of:

C:\WIN95\Program Files\APP\HELPTEXT.HLP

This restriction does not apply in U/Gi 4.

The CONTEXT parameter specifies the numeric id, stored in the help file, which refers to a particular topic. This enables the selection of the particular help information (from the specified help file) to be displayed when help is actioned. This context id should match the id defined for the appropriate page when the help file was created. Refer to the supplier of the help file for a list of the available context ids.

Note: U/Gi 4 can display both 16 and 32 bit help files. U/Gi 3.10 is a 16 bit Windows application and can only use 16 bit Windows help files with this statement. U/Gi 3.10 cannot display 32 bit Windows help files.

Neither version of U/Gi can display DOS-format help files, even though they have the same file extension as Windows Help files.

Applies To

U/Gi Help file

Example

...

REM Set context sensitive help to 1024 (topic on this screen)

SETHELP("c:\temp\testhelp.hlp",1024)

Display this entry screen

REM Set this back to the main topic of the help file

SETHELP("c:\temp\testhelp.hlp",0)


SETINMAX

SETINMAX ---------- Sets the decimal value for the maximum number of characters allowed on INPUT

Type

U/BL statement.

Syntax

SETINMAX value

Description

The SETINMAX statement sets the decimal value for the maximum number of characters allowed on INPUT. The default value for this parameter is 132 whenever the U/BL prompt or password screen is displayed.

If you want an automatic unpend, you must set value to the negative of the maximum number of characters. Selecting an automatic unpend causes the INPUT to be returned automatically as soon as the maximum number of characters represented by value is reached.

If the DataGeneral compatibility statement is set to ON, SETINMAX is effective only for the next INPUT statement, and the default value of 132 is reset.

The SETINMAX statement is equivalent to the STMA 4,10 statement.


SETIKEY1

SETIKEY1 ---------- Sets the decimal value of the primary interrupt key

Type

U/BL statement.

Syntax

SETIKEY1 value

Arguments

value

A numeric expression that sets the new value for the primary interrupt key.

Description

The SETIKEY1 statement sets a new decimal value for the primary interrupt key. See the GETIKEY1 and ON IKEY statements for more information.

It is equivalent to the STMA 4,6 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets the value of the primary interrupt key.

10 INPUT " New value for primary interrupt key", X

20 SETIKEY1 X :Set a new primary interrupt key value.

30 GETIKEY1 Y

40 PRINT "The new value for the primary interrupt key is"; Y


SETIKEY2

SETIKEY2 ---------- Sets the decimal value of the secondary interrupt key

Type

U/BL statement.

Syntax

SETIKEY2 value

Arguments

value

A numeric expression that sets the new value for the secondary interrupt key.

Description

The SETIKEY2 statement sets a new decimal value for the secondary interrupt key. See the GETIKEY2 and ON IKEY statements for more information.

It is equivalent to the STMA 4,7 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets the value of the secondary interrupt key.

10 INPUT " New value for second ary interrupt key", X

20 SETIKEY 2 X :Set a new secondary interrupt key value.

30 GETIKEY 2 Y

40 PRINT "The new value for the secondary interrupt key is"; Y


SETLEN

SETLEN ---------- Sets the maximum length of an Editbox

Type

Windows Object Command.

Syntax

SETCOLOR(ID, MAXLEN [,STAT])

Arguments

ID | The ID number of the Editbox.
MAXLEN | The maximum number of characters in the Editbox.
STAT | The status variable.

Description

The maximum number of characters that can be entered in an Editbox may be specified using SETLEN.

For example, SETLEN(1,10, STAT ) would limit the number of characters entered into Editbox ID 1, to 10. If more text is already present in the Editbox than the specified maximum, the user will be able to delete chars but not add them. SETLEN(1,0, STAT) will remove any text length limit.

Example

REM Remove any existing Windows objects or U/BL windows

DELETEWO(-1)

WINIT (ER)

REM Define working storage

DIM NEWLINE$[1]

DIM MESSAGE$[10]

DIM NAME$[100],ADDRESS1$[100],ADDRESS2$[100],ADDRESS3$[100]

REM Declare the object unpend character as ASCII 10

LET NEWLINE$="<10>"

LET OBJUNPEND=5

SETGUIOPT(OBJUNPEND,NEWLINE$)

REM Draw the input window complete with edit boxes & buttons

REM Define the Windows objects' flags

REM Edit box specific flags

LET HANDLEENTER=1024

LET HANDLETAB=2048

REM Button specific flags

LET AUTOFOCUS=2048

LET NOTIFYCHANGE=512

REM Generic flags - apply to all Windows objects

LET TABSTOP=1

REM Draw and show window

WMAKE ("Input",7,23,13,34,7,ER)

WSHOW ("Input",ER)

REM Write labels on base window

PRINT @(-30);@(2,2);"Name";@(4,2);"Address"

REM Define the edit boxes as tab stops

LET MODE=HANDLETAB+TABSTOP

EDITBOX(1,2,10,1,20,"",MODE)

EDITBOX(2,4,10,1,20,"",MODE)

EDITBOX(3,5,10,1,20,"",MODE)

EDITBOX(4,6,10,1,20,"",MODE)

REM Limit NAME to 20 characters and ADDRESS lines to 40 characters each

SETLEN (1, 20)

SETLEN (2, 40)

SETLEN (3, 40)

SETLEN (4, 40)

REM Define the controlling buttons as tab stops which return

REM a message on selection and return focus to the U/BL base-panel

LET MODE=TABSTOP+NOTIFYCHANGE+AUTOFOCUS

BUTTON (5,8,6,2,8,"OK",MODE,ER,"")

BUTTON (6,8,19,2,8,"Cancel",MODE,ER,"")

REM Define and set the initial values for the edit boxes

LET NAME$="Mr D.Smith"

LET ADDRESS1$="20,Big Street"

LET ADDRESS2$="Sometown"

LET ADDRESS3$="ST2 1OU"

SETTEXT (1,NAME$)

SETTEXT(2,ADDRESS1$)

SETTEXT(3,ADDRESS2$)

SETTEXT(4,ADDRESS3$)

DIM LAST$[100]

REM Explicitly set the focus to the first edit box

SETFOCUS (1,STAT)

REM Switch off echo (to hide button messages)

STMA 6,0

REM Allow user to edit data and wait for a button press

$DO_WHILE MESSAGE$<>"@^5;" AND MESSAGE$<>"@^6;"

INPUT "",MESSAGE$

$END_DO

REM Process button press

IF MESSAGE$="@^5;" THEN

REM 'OK' button pressed, read name and address the user has entered

GETTEXT (1,NAME$)

GETTEXT(2,ADDRESS1$)

GETTEXT(3,ADDRESS2$)

GETTEXT(4,ADDRESS3$)

ELSE

REM Input rejected by user, nullify data

LET NAME$,ADDRESS1$,ADDRESS2$,ADDRESS3$=""

END IF

REM Restore echo; close down and destroy window/objects

STMA 7,0

DELETEWO(-1)

WHIDE ("Input",ER)

WDELETE ("Input",ER)

Running the above program produces the following results:

Click the Cancel button to return to the U/BL prompt.

See Also

EDITBOX


SETLINECAN

SETLINECAN ---------- Sets the value of the line cancel character

Type

U/BL statement.

Syntax

SETLINECAN new value

Arguments

new value

A numeric expression which becomes the new value of the line cancel character.

Description

The SETLINECAN statement sets the new value of the key that is used to cancel an entire line. This is the decimal value that the line cancel key on the terminal sends to U/BL when that key is pressed. The default value is 127.

The SETLINECAN statement is equivalent to the STMA 4,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 4,1.


_SETMREC

SETMREC ---------- Updates the maximum number of records that can be held in a file

Type

U/BL command and statement

Syntax

SETMREC(maxrec,chan)

Arguments

maxrec | The new maximum number of records in the file
chan | The channel number of the file you wish to change. The file must be OPEN.

Description

The SETMREC statement updates the maximum number of records that can be held in a file (file types "D", "I", or "J"), by setting bytes 22-24 of the file's FCB to the number specified by maxrec.

Basic will generate the error:

77 - invalid record number

if maxrec is less than the current value held in bytes 22-24 of the FCB.

Example

:

00200 _SETMREC(NREC,1)

:


SETNUMBER

SETNUMBER ---------- Sets the numeric value associated with a Windows object

Type

Windows Object Command

Syntax

SETNUMBER(ID, VALUE [, STAT])

Arguments

ID | The unique handle of the Windows object
VALUE | The state to which to set the Windows object
STAT | Optional status return

Description

The SETNUMBER command sets the numeric state of a Windows object which varies from object to object. For a combo box, dropdown combo box, list box or dropdown list, it is the index of the currently selected item (starting from 0). For radio buttons and check boxes this statement sets the current on-off state.

With Edit boxes, the SETNUMBER command can be used to highlight all or part of the text displayed in the Edit box.

For objects where no numeric state can be associated with the object, this statement has no effect on the object.

For edit boxes, the SETNUMBER command can be used to highlight text within the edit boxes. To do this set the VALUE parameter as follows:

VALUE = start char +256 * end char | To highlight the text specified between the start char and end char characters.
VALUE = -1 | To highlight all the text
VALUE = 0 | To deselect the text held in an Edit box.

For example, for an edit box containing the text: "Clear Highlighted clear", set VALUE to 7+(256*17) to highlight the word "highlighted"

Note: When using SETNUMBER against radio buttons that are in a radio group, the mutually exclusivity of the buttons is not respected. In other words, using SETNUMBER to change the state of a radio button only alters the state of that button, even if this will result in two buttons in the radio group from being selected at the same time.

Applies To

Check boxes

Combo boxes

Dropdown combo boxes

Dropdown lists

List boxes

Radio buttons.

Example

REM *** Create a combo box ***

COMBOBOX(1,5,5,5,40," Initial Selection | Line1 | Line 2 ",32)

DELAY 30

REM *** Select the second option ('Line 2') ****

SETNUMBER(1,1)

PRINT "<7>"

DELAY 30

REM *** Clear up and return ****

DELETEWO(-1)

END

See Also

BUTTON

COMBOBOX

EDITBOX

GETNUMBER

GETTEXT

LISTBOX

RADIOBUTTON

SETTEXT


SETPORT

SETPORT ---------- Changes the port characteristics

Type

U/BL statement.

Syntax

SETPORT port#,baud,data bits,stop bits,parity,cts

Arguments

port# | A numeric expression specifying the port number to be changed
baud | A numeric expression specifying the new baud rate
data bits | A numeric express specifying the number of data bits. This value can be 7 or 8.
stop bits | A numeric expression specifying the number of stop bits. This value can be 1 or 2.
parity | A string variable or literal whose first byte is the new parity. This can be N (no parity), M (mark), S (space), E (even), or O (odd).
cts | A numeric expression specifying whether clear-to-send is to be used. This can be 0 (do not use clear-to-send) or 1 (use clear-to-send).

Description

The SETPORT statement changes the port characteristics as described above. Make sure that you do not enter invalid information, as BASIC only detects an invalid port (#ERR=89) and an invalid parity (#ERR=80).

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


SETPRTKIND

SETPRTKIND ---------- SETs the decimal value of the current I/O port pass through printer "kind"

Type

U/BL statement.

Syntax

SETPRTKIND new value

Arguments

new value

A numeric expression which holds the new value for the current I/O port pass through printer "kind".

Description

A SETPRTKIND statement sets the new value for the current I/O port pass through printer "kind".

It is equivalent to the STMA 4,19 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets the value of the current pass through printer "kind".

10 INPUT "New printer 'kind'" ,X

20 SETPRTKIND X :SET PASS THROUGH PRINTER KIND

30 GETPRTKIND X

40 PRINT "The value of the pass "; :PRINT THE VALUE

50 PRINT "Through printer kind for the current I/O port is";X


SETQUEUE

SETQUEUE ---------- Sets the default output name

Type

U/BL statement.

Syntax

SETQUEUE device name

Arguments

device name

A string variable or literal containing the new default output device name.

Description

The SETQUEUE statement changes a location in the current task. This location is known as the default output device name, although you can enter any 7 characters. Another program in the current task can retrieve these characters via the GETQUEUE statement (or the STMA 9,3 statement).

If the current length of the string is less than 7 for SETQUEUE, only the current length is moved to device name.

The SETQUEUE statement is equivalent to the STMA 10,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 10.


SETSEA

SETSEA ----------- Sets the search list for the current task

Type

U/BL statement.

Syntax

SETSEA list$

Arguments

lists$

A string variable containing the new search list.

Description

The SEATSEA statement is used to set the search list of the current task. Each two bytes contain a drive number in the first byte and a user group in the second byte. The first drive and user group combination is the default drive and user group.

U/BL only maintains and allows six drive and user group combinations. If you enter more than six, they are truncated.

If the current length of the string contains less than six combinations of drive and user group, the trailing drive and user group are left intact. This allows the default drive and user group to be changed while leaving the rest of the search list intact.

If you want to shorten the search list, pad the string with nulls to remove unwanted trailing combinations of drive and user group.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


SETSWAPLEV

SETSWAPLEV ---------- Sets the current swap level

Type

U/BL statement.

Syntax

SETSWAPLEV newvalue

Arguments

newvalue

A numeric expression which becomes the new value of the item.

Description

The SETSWAPLEV statement sets the current swap level to a new value.

The way that SETSWAPLEV works depends on how the DGCOMP switch is set:

  • If DGCOMP is OFF, a SETSWAPLEV n (for any value of n) has no effect on the program

  • If DGCOMP is ON, SETSWAPLEV n RESETs the swap level to n, as long as n is less than the current value of SYS(24). (If n is not less than the current value of SYS(24), the SETSWAPLEV is ignored.)

The SETSWAPLEV statement is equivalent to the STMA 4,11 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


SETSYSBITS

SETSYSBITS ---------- Retrieves the system flag bits affecting how the unpend key is treated in INPUT string and the @INPUT field

Type

U/BL statement.

Syntax

SETSYSBITS newvalue

Description

The SETSYSBITS statement SETs the information in the system flags Bit 0 and Bit 1.

The flags have the following effect:

Bit 0

If bit 0 is set to 1, and input is being taken at the rate of one character at a time, then the primary unpend or <return> key, (CHR$13), is not placed in the INPUT string. (This is compatible with Data General.)

Bit 1

If bit 1 is set to 1, the primary unpend that is typed into the first position of an @INPUT field keeps the field intact as if the secondary unpend key had been entered. The primary unpend in any other position still blanks the remainder of the field.

If bit 1 is set to 0, the primary unpend character in the first position of an @INPUT field blanks the entire field. This is the default.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.


SETTABSZ

SETTABSZ ---------- Sets the decimal value for the number of spaces between tab stops

Type

U/BL statement.

Syntax

SETTABSZ value

Arguments

value

A numeric expression that is the new value for the number of spaces between tab stops.

Description

The SETTABSZ statement sets the decimal value of the number of spaces between tab stops. You make use of this value when you use commas instead of semicolons for field delimiters in the PRINT statement. The default value is 15.

The SETTABSZ statement is equivalent to the STMA 4,9 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets a new decimal value for the number of spaces between tab stops.

10 DIM NUM$ (10)

20 DATA "ONE", "TWO", "THREE", "FOUR", "FIVE", "SIX"

30 FOR I = 1 TO 6 \ READNUM$ \ PRINT NUM$ \ NEXT I \ RESTORE \ PRINT

40 GETTABSZ X

50 PRINT "There are currently " ; X; "spaces between tabs."

60 X = X - 2

70 SETTABSZ X

80 FOR I =1 TO 6 \ READ NUM$ \ PRINT NUM$ \ NEXT I \ RESTORE \ PRINT

90 PRINT "There are currently " ; X; "spaces between tabs."

100 END


SETTEXT

SETTEXT ---------- Sets the text associated with a Windows object or text box

Type

Wndows Object Command

Syntax

SETTEXT(ID, TEXT$ [, STAT])

Arguments

ID | The unique handle of the Windows object
TEXT$ | The new text for the object.
STAT | Optional status return

Description

The SETTEXT statement allows the text associated with a Windows object to be changed under program control. For example, when a new customer is selected, fields on the screen must be updated to display the new data.

The text associated with a Windows object varies from object to object. For instance, in an edit box it is the text in the box itself. For a check box or a radio button it is the button's label and for buttons it is either the text displayed on the button (push buttons) or the set of the bitmaps used (bitmap buttons).

For a multi-column list box, SETTEXT can be used to set the column widths by specifying a set of comma-separated values. Each value represents the column width in characters. Multi-column LISTBOXes can be created by using style 512 at creation time. Text added to such a list box should be separated by the tab character (ASCII 9) to indicate the column breaks.

Applies To

Buttons

Check boxes

Combo boxes

Edit boxes

Radio buttons

Text boxes.

Example

REM *** Create the edit boxes ****

EDITBOX(1,5,5,1,40,"Name",0)

EDITBOX(2,7,5,1,40,"Address 1",0)

EDITBOX(3,8,5,1,40,"Address 2",0)

REM **** Here we get the customer code, and ****

REM **** lookup the customer details into ****

REM **** NAME$, ADDRESS1$, and ADDRESS2$ ****

REM *** Change the displayed text ****

SETTEXT(1,NAME$)

SETTEXT(2,ADDRESS1$)

SETTEXT(3,ADDRESS2$)

REM **** Rest of program here

REM *** Clear up and return ****

DELETEWO(-1)

END

See Also

BUTTON

EDITBOX

GETNUMBER

GETTEXT

RADIOBUTTON

SETNUMBER

TEXTBOX


SETTYPE

SETTYPE ---------- Sets the terminal type

Type

U/BL Statement.

Syntax

SETTYPE value

Arguments

value

A numeric expression that is moved to the proper U/BL field.

Description

The SETTYPE statement changes the terminal type that was originally specified when U/BL was configured. The value of SETTYPE can be between 1 and 4. SETTYPE moves the value of the terminal type into the U/BL field.

The SETTYPE statement is equivalent to the STMA 2,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for GETTYPE.


SETUNPEND1

SETUNPEND1 ---------- Sets a new decimal value for the primary unpend character

Type

U/BL Statement.

Syntax

SETUNPEND1 value

Arguments

value

A numeric expression that becomes the new primary unpend character

Description

The SETUNPEND1 statement sets a new value for the key that performs the primary unpend. An unpend character terminates an INPUT statement.

When a program ends and returns to the U/BL prompt or the password screen, the primary unpend is set to a default value of 13 (carriage return).

The SETUNPEND1 statement is equivalent to the STMA 4,4 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets a new value for the primary unpend character.

10 INPUT "NEW PRIMARY UNPEND CHARACTER" ,X

20 SETUNPEND1 X :SET NEW PRIMARY UNPEND CHARACTER

30 GETUNPEND1 X

40 PRINT "The value of the primary" :PRINT THE VALUE

50 PRINT "Unpend character is" ;X


SETUNPEND2

SETUNPEND2 ---------- Sets a new decimal value for the secondary unpend character

Type

U/BL Statement.

Syntax

SETUNPEND2 value

Arguments

value

A numeric expression that becomes the new secondary unpend character.

Description

The SETUNPEND2 statement sets a new value for the key that performs the secondary unpend. An unpend character terminates an INPUT statement.

When a program ends and returns to the U/BL prompt or the password screen, the secondary unpend is set to a default value of 10 (line feed).

The SETUNPEND2 statement is equivalent to the STMA 4,5 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets a new value for the secondary unpend character.

10 INPUT "NEW SECONDARY UNPEND CHARACTER" ,X

20 SETUNPEND2 X :SET NEW SECONDARY UNPEND CHARACTER

30 GETUNPEND2 X

40 PRINT "The value of the secondary" :PRINT THE VALUE

50 PRINT "Unpend character is" ;X


SETUNPEND3

SETUNPEND3 ---------- Sets a new decimal value for unpend character 3

Type

U/BL Statement.

Syntax

SETUNPEND3 value

Arguments

value

A numeric expression which will become the new unpend character 3.

Description

SETUNPEND3 sets a new value for the key that performs the unpend character 3. An unpend character terminates an INPUT statement.

When a program ends and returns to either the U/BL prompt or the password screen, unpend character 3 is set to no default (255).

The SETUNPEND3 statement is equivalent to the STMA 4,16 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets a new value for unpend character 3.

10 INPUT "NEW UNPEND CHARACTER 3" ,X

20 SETUNPEND3 X :SET NEW UNPEND CHARACTER 3

30 GETUNPEND3 X

40 PRINT "The value of unpend character 3" :PRINT THE VALUE

50 PRINT "Unpend character is" ;X


SETUNPEND4

SETUNPEND4 ---------- Sets a new decimal value for unpend character 4

Type

U/BL Statement.

Syntax

SETUNPEND4 value

Arguments

value

A numeric expression that becomes unpend character 4.

Description

The SETUNPEND4 statement sets a new value for the key that performs unpend character 4. An unpend character terminates an INPUT statement.

When a program ends and either returns to the U/BL prompt or the password screen, unpend character 4 is set to no default (255).

The SETUNPEND4 statement is equivalent to the STMA 4,17 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program sets a new value for unpend character 4.

10 INPUT "NEW UNPEND CHARACTER 4" ,X

20 SETUNPEND4 X :SET NEW UNPEND CHARACTER 4

30 GETUNPEND4 X

40 PRINT "The value of unpend character 4" :PRINT THE VALUE

50 PRINT "Unpend character is" ;X


SETXTRAINF

Type

U/BL statement.

Syntax

SETXTRAINF(ID,1,LIC$)

Arguments

ID | The handle of the ActiveX control
LIC$ | The license string.

Description

Many ActiveX controls can present a user interface to allow program designers to configure the control. This is usually in the form of a series of property sheets that control how the control works. These property sheets can be displayed by calling SETXTRAINF(ID,1,"") on the control.


SGN

SGN ---------- Returns the sign of its argument

Type

U/BL Function.

Syntax

SGN(expr)

Arguments

expr

Any numeric expression.

Documents

The SGN function returns 1 if its argument is positive, 0 if it is zero or -1 if the argument is negative.

Example

* list

00010 DIM DESC$[#2,10]

00020 LET DESC$[#0]="NEGATIVE" \ DESC$[#1]="ZERO" \ DESC$[#2]="POSITIVE"

00060 INPUT "Enter a number (999 to finish).........",X;

00070 $DO_WHILE X<>999

00080 PRINT ,DESC$[#SGN(X)+1]

00090 INPUT "Enter another number (999 to finish)...",X

00100 $END_DO

* run

Enter a number (999 to finish).........4321 POSITIVE

Enter another number (999 to finish)...-5 NEGATIVE

Enter another number (999 to finish)...0 ZERO

Enter another number (999 to finish)...999

See also

ABS


SHARE

SHARE ---------- Indicates that the module is shareable

Type

U/BL command and statement

Syntax

SHARE(pkg$)

Arguments

pkg$

A string expression containing the module's name.

Description

The SHARE statement indicates that module is shareable. This should be the first statement in a shareable program.

Example

00010 SHARE ("IOPKG")

See Also

Shared Memory Procedures


SHFT

SHFT ---------- Performs a left or right shift

Type

U/BL Function.

Syntax

SHFT(expression, num_bits)

Arguments

expression | Any numeric expression.
num_bits | The number of bits to shift. If num_bits is negative, a right shift is performed, while if num_bits is positive, the shift is to the left.

Description

The SHFT function moves the bits of the expression given the specified number of bits to the left or right, depending on whether the num_bits parameter is positive or negative. Bits are not rotated; zeroes replace the bits moved from the end.

Example

*list

00010 LET X=1

00020 FOR I=0 TO 10

00030 PRINT I;SHFT(X,I),

00040 NEXT I

* run

0 1 1 2 2 4 3 8 4 16 5 32

6 64 7 128 8 256 9 512 10 1024


SHMREAD

SHMREAD ----------- Copies the contents of the user shared memory

Type

U/BL command and statement

Syntax

SHMREAD(str$)

Arguments

str$

Receives the contents of the shared memory.

Description

The SHMREAD statement copies the contents of the user shared memory into the str$ parameter.

Note: As with all such statements, SHMREAD can be prefixed with a REM.

Example

* shmsize(n)

* ;n

512

* dim x$[512]

* shmread(x$)

See also

SHMSIZE

SHMWRITE


SHMSIZE

SHMSIZE ---------- Returns the size of the user shared memory area (in bytes)

Type

U/BL command and statement

Syntax

SHMSIZE(n)

Arguments

n

The size of the user memory area in bytes.

Description

The SHMSIZE statement returns the size of the user shared memory area (in bytes) into the n paramter.

Note: As with all such statements, SHMSIZE can be prefixed with a REM.

Example

* shmsize(n)

* ;n

512

See also

SHMREAD

SHMWRITE


SHMWRITE

SHMWRITE ---------- Writes information to the users shared memory

Type

U/BL command and statement

Syntax

SHMWRITE(str$)

Arguments

str$

Contains the information that is to be written into the shared memory.

Description

The SHMWRITE statement copies the contents of the str$ parameter into the user shared memory.

Note: As with all such statements, the SHMWRITE statemnt can be prefixed with a REM.

Example

* shmsize(n)

* ;n

 512

* dim x$[512]

* x$="<information you want written into the shared memory>",fill$(0)

* shmwrite(x$)

See also

SHMREAD

SHMSIZE


SHOWWO

SHOWWO ---------- Shows or hides a Windows object or a text box

Type

Windows Object Command

Syntax

SHOWWO(ID, STATE, [, STAT])

Arguments

ID | The unique handle of the Windows object
STATE | The visibility of the Windows object
STAT | Optional status return

Description

The SHOWWO command is used to hide or show individual Windows objects. This can be useful where parts of a form are dependent on other parts. To display a previously hidden Windows object (or to ensure the object is displayed) call SHOWWO with a STATE of '1'. To hide an object, call this statement with a STATE of '0'. To hide or show all of the currently defined objects, specify an ID of -1.

To show or hide a range of Windows Objects, add 16 times the number of Windows Objects in the range to the second value, for example:

SHOWWO(100,1+16*20) | Show all objects in the range 100-119
SHOWWO(20,0+16*5) | Hide all objects in the range 20-24

Note: All controls in the range need not exist. They will be shown or hidden only if a control of the appropriate value exists.

Applies To

All Windows objects with a handle

Text boxes

See Also

BUTTON

COMBOBOX

DELETEWO

EDITBOX

ENABLEWO

LISTBOX

RADIOBUTTON

SETFOCUS

TEXTBOX


SIGNAL

SIGNAL ---------- Send a signal to a specified job

Type

U/BL command.

Syntax

SIGNAL(job,sig_type,stat)

Arguments

job | The job to send the signal to. This is the SYS(9) value of that job.
sig_type | This can be one of the following: 2 - send the primary IKEY 3 - send the secondary IKEY 15 - BYE the job off 9 - delete the job. Note: Only use sig_type set to 9 as a last resort.
stat | This can be one of the following: 0 - signal passed successfully 1 - invalid job number 2 - no process running 3 - no privileges 4 - invalid signal type

Description

The SIGNAL command sends a signal to a specified job. To overcome any privilege problems, you must run this command with the same effective user id for all users. This can be done by using the following UNIX command:

chmod +s ubl

This means that whenever U/BL is run, each session will have the same effective user id. This user id is determined by the user who owns ubl.

ls -l ubl

will give the owner of ubl. Ensure that this user has the necessary privileges to access all data files.

Example

* signal(2,15,er)

This causes the job with a SYS(9) value of 2 to do a BYE.


SIZE

SIZE --------- Shows the settings for the environment variables which use memory

Type

U/BL statement.

Syntax

SIZE(nlines,nsvar,nnvar,code,string,numerics,chan,windows)

Arguments

nlines | Returns the number of free program lines
nsvar | Returns the number of free string variables
nnvar | Returns the number of free numeric variables
code | Returns the number of free bytes for program code
string | Returns the number of free bytes for string data
numerics | Returns the number of free array elements
chan | Returns the number of free channels
windows | Returns the number of free bytes in the window buffer.

Description

The SIZE statement returns the same values as would be returned by typing SIZE at the '*' prompt.

Note: All of the arguments are required, and that they must be in the order as listed above.

Example

If you are only interested in the number of free bytes for string data, you could use either of the following:

00150 SIZE(NLINES,NSVAR,NNVAR,CODE,STRING,NUMERICS,CHAN,WINDOWS)

which means using eight variable names, or:

00150 SIZE(I,I,I,I,STRING,I,I,I)

where "I" is a local scratch variable used throughout your program.

See also

SIZE


SIZE

SIZE --------- Shows the settings for the environment variables which use memory

Type

U/BL command.

Syntax

SIZE

Description

The SIZE command displays the settings for the various environment variables which configure the user defined portion of memory.

Example

Table | Size | Used | Free
CHANNELS | 256 | 256 | 0
HELP MEMORY (BBHMEM) | 3072 | 3072 | 0
HELP MEMORY (BBHTEXT) | 35328 | 35328 | 0
COMMON BLOCK | 2048 | 512 | 1536
INODE CACHE | 256 | 256 | 0
CHFREEZE MEMORY | 5120 | 5120 | 0
WINDOWS | 20480 | 20480 | 0
CODE | 33280 | 0 | 33280
LINES | 2048 | 0 | 4048
LABELS | 1024 | 8 | 1016
NPOOL | 2048 | 0 | 2048
NUMERIC COUNT | 144 | 0 | 144
INITIALISED | 144 | 0 | 144
STRING COUNT | 144 | 0 | 144
STRING EXTRA | 469 | 1 | 468
SCALAR NUMBERS | 144 | 0 | 144
VECTOR NUMBERS | 944 | 0 | 944
STRING DATA | 12800 | 0 | 12800

The first set of tables are fixed and so will not be re-sized by U/BL. The second set will be changed at run time to accommodate different programs if there is not enough available memory.

At the side of the display is the following information.

Swap Levels.

  on disk : 0

  in memory : 1

Max swap disk used:

  0 bytes

Allocated : 187392

Available : 336896

Max. Usage : 188928

Total Usage : 524288

When an application is SWAPping, U/BL will try to maintain the programs in memory. Depending on how large the programs are and what the BBMEMPOOL environment variable is set to, a certain number will have to be swapped to disk. The first set of figures show how many programs are in memory and how many are on disk.

The third figure shows what the largest size of the swap file was. BBMEMPOOL could be increased so that no disk based swap file is used if the system has sufficient memory and this will increase overall system performance.

The last four figures show how much of BBMEMPOOL has been used. If the "Max. Usage" is much lower than "Total Usage" after running the application then BBMEMPOOL has been set too high which could adversely affect performance on a multi-user system since there would be less memory available for other processes.

See also

BBMEMPOOL


SLINIT

SLINIT ---------- Reinitialises the shared library

Type

U/BL statement.

Syntax

SLINIT

Description

The SLINIT statement reinitializes the shared library. It will remove all current programs from the shared library.

It is recommended you only use this statement in a development/debugging scenario.

See Also

Shared Memory Procedures


_SLIST

SLIST ---------- Lists the contents of the global shared procedures library

Type

U/BL statement.

Syntax

SLIST

Description

The SLIST statement lists the contents of the global shared procedures library.

Example

* slist

Loc | Module | Entry | Line No. | Arguments
--- | ------ | ----- | -------- | ---------
000000 | TEST | PRINIT | 1000 | S N

000fc4 (Free)

0027fc

See Also

Shared Memory Procedures


SLOAD

SLOAD ---------- Loads the screen with the content of s$

Type

U/BL Statement or Command.

Syntax

SLOAD(s$)

Arguments

s$

A string variable DIMensioned large enough to hold 2 bytes for each character position plus 8 bytes of header information, for example, for a full screen, s$ should be DIMensioned to 2*(24*80)+8, or 3848, bytes.

Description

The SLOAD statement loads the screen with the content of s$, at its original location.

Example

00100 SLOAD(S$)

See also

$SCREEN_LOAD

$SCREEN_STORE

SSTORE


SLOCK

SLOCK FILE ---------- Performs a SuperDOS lock on one or more records

Type

U/BL Statement.

Syntax

SLOCK FILE(channel,recnum)[,num]

Arguments

channel | A numeric expression specifying a channel number on which a file is opened.
recnum | A numeric variable that specifies the starting record number to lock.
num | An optional numeric expression that specifies the number of records to lock, in the range of 1 to 255. If omitted, 1 is assumed. The number of records must be less than or equal to 255. The Business BASIC run-time processor (TOKEN) only looks at the value in the low byte. Therefore, if the numeric expression evaluates to a number greater than 255, only the low byte is used (that is, num =MOD(num,256) ).

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The SLOCK command performs a U/BL record lock on one or more records in the specified file. This lock prevents any user, regardless of which language is used, from writing to the locked records. The records to locked are specified starting at the value of recnum, and the number of records to be locked is specified by num. The default value of num is 1, and the maximum is 255.

U/BL locks are kept in a table that lists the actual bytes locked. The record number specified in the SLOCK statement is converted into a range of bytes and entered into this table.

If the READLOCK is OFF, the record that has been locked with SLOCK cannot be read by another user. If AUTOLOCK is ON, this means that SLOCK is in effect when a record is read, and SUNLOCK is performed automatically when a record is written. The SUNLOCK statement performs the unlock required for a record. SUNLOCK is performed automatically:

  • when you delete a record using a RDEL or RKDEL statement

  • on all the records in a file when you close the file

  • on all the records in all of your files when control is returned to the U/BL coimmand line or the SYE program

If you try to perform a SLOCK on a record that has already been locked with SLOCK or BYTELOCK by another task, a run time error (#ERR=30) occurs. When this error occurs, the program needs to wait for the record to be unlocked with SUNLOCK, or the program must process another record.

In a typical program, the SLOCK is performed before a record is read into memory. The user or the program then modifies the record, and it is written back to the file where it is unlocked using SUNLOCK. This means that there are no conflicts where several users could potentially update the same record at the same time. If the record is locked, a message is displayed that informs the user that the record is in use.

You can use SLOCK to work throughout a SuperLAN network, as it locks parts of specific files.

Note: The functionality provided by the environment variable setting BBSLOCK=N is not supported due to current Windows restrictions.


SOCKACCEPT

SOCKACCEPT ---------- Accepts an incoming connection on a server socket, and creates a new client socket to communicate with it

Type

U/BL Socket command

Syntax

SOCKACCEPT(SERVSOCK,CLISOCK [,STAT])

Arguments

SERVSOCK | A server socket that has previously been created with SOCKSERV
CLISOCK | A valid unused socket number that will be used to communicate with the incoming connection
STAT | Optional status return

Description

The SOCKACCEPT command accepts an incoming connection on a server socket, and creates a new client socket to communicate with it.

Example

SOCKACCEPT(0, 1 ,STAT)


SOCKCLOSE

SOCKCLOSE ---------- Closes a socket, or closes all open sockets

Type

U/BL Socket Command

Syntax

SOCKCLOSE(SOCKET [,STAT])

SOCKCLOSE()

Arguments

SOCKET | A valid socket
STAT | Optional status return

Description

The SOCKCLOSE command closes a socket, or with the second syntax closes all open sockets.

Examples

SOCKCLOSE(1)

SOCKCLOSE()


SOCKCONN

SOCKCONN ---------- Creates a socket and attempts to connect to a remote server

Type

U/BL Socket command.

Syntax

SOCKCONN(SOCKET, HOST$ [,STAT])

Arguments

SOCKET | A valid unused socket number (from 0 to MAXSOCKETS-1)
HOST$ | A string variable which specifies the remote server in the format "hostname:port", for example, "www.transoft.com:32". This must be specified as shown in the example below.
STAT | Optional status return

Description

The SOCKCONN command creates a socket and attempts to connect to a remote server.

Example

The following command attempts to connect to your machines local Telnet port:

DIM HOST$[20]

HOST$="localhost:23"

SOCKCONN(1,HOST$,STAT)


SOCKFREE

SOCKFREE ---------- Returns a valid unused socket number

Type

U/BL Socket command.

Syntax

SOCKFREE(SOCKVAR [,STAT])

Arguments

SOCKVAR | A variable that returns the number of a valid unused socket, or -1 if all sockets are in use
STAT | Optional status return

Syntax

The SOCKFREE command returns a valid unused socket number.

Example

SOCKFREE(MYSOCK)

IF MYSOCK<>-1 THEN

SOCKCONN(MYSOCK,HOST$,STAT)

ELSE

PRINT "All sockets are in use"

STOP

END IF


SOCKRECV

SOCKRECV ---------- Receives data from a previously-created socket

Type

U/BL Socket command.

Syntax

SOCKRECV(SOCKET, DAT$, DATLEN [,STAT])

Arguments

SOCKET | A valid unused socket number (from 0 to MAXSOCKETS-1)
DAT$ | A string variable that will receive the data
DATLEN | A variable that specifies the maximum data requested, and receives the amount of data sent
STAT | Optional status return.

Description

The SOCKRECV command receives data from a previously created socket. This command returns immediately with available data, and does not wait for all DATLEN bytes to be received. This is because socket applications usually allow variable-length data to be sent where the length cannot be determined until some data is received.

Example

DIM A$[100]

LDAT=100

SOCKRECV(1,A$,LDAT,STAT)


SOCKSEND

SOCKSEND ---------- Sends data down a previously-created socket

Type

U/BL Socket command.

Syntax

SOCKSEND(SOCKET, DAT$, DATLEN [,STAT])

Arguments

SOCKET | A valid unused socket number (from 0 to MAXSOCKETS-1)
DAT$ | A string variable which specifies the data to be sent.
DATLEN | The length of the data to be sent. If DATLEN is -1 then all the data in the string is sent.
STAT | Optional status return.

Description

The SOCKSEND command sends data down a previously-created socket.

Example

SOCKSEND(1,DAT$,-1,STAT)

SOCKSEND(1,A$,LEN(A$),STAT)


SOCKSERV

SOCKSERV ---------- Creates a server socket that listens on a port

Type

U/BL Socket command

Syntax

New Syntax: SOCKSERV(SERVSOCK, PORT, REUSE, STAT)

Old  Syntax: SOCKSERV(SERVSOCK, PORT [,STAT])

Arguments

SERVSOCK | A valid unused socket number
PORT | The TCP/IP port on which the server socket waits for connections
REUSE | A numeric variable or a numeric expression that can be set to 0 or 1. If you use this parameter then the STAT parameter (see below) must also be used.
STAT | Optional status return. This must be set if you are using the REUSE parameter defined above.

Description

The SOCKSERV command creates a server socket that listens for connections on a port. When waiting on a server socket using the SOCKWAIT command, a return indicates that a connection is waiting to be accepted rather than data being available. After the connection has been accepted, SOCKWAIT reverts to indicating data is available to be read.

New syntax for the SOCKSERV command has been introduced to solve the following problem:

The SOCKSERV command returns STAT=9 when a process on the computer is already bound to the same fully-qualified address and the socket has not been marked to allow address reuse with SO_REUSEADDR.

In such a scenario if the REUSE parameter is set to 1 then the SOCKSERV command will allow the address to be reused.

If the original syntax is used or REUSE is set to 0 then the SOCKSERV command will not allow the address to be reused.

A new environment variable, BBSOCKREUSE has been implemented . If BBSOCKREUSE is set to 'Y' then the SOCKSERV command will mark sockets for address reuse whether the new or the old syntax for SOCKSERV is used.

Example

SOCKSERV(0,23)

SOCKWAIT(0,100000,RETVAL,STAT)

IF RETVAL=0 THEN

SOCKACCEPT(0,1,STAT)

END IF

See Also

BBSOCKREUSE


SOCKWAIT

SOCKWAIT ---------- Sets the text associated with a Windows object or text box

Type

U/BL Socket command.

Syntax

SOCKWAIT(SOCK1, [, ... SOCKN], TIMEOUT, VALIDSOCK,STAT)

SOCKWAIT(-1, TIMEOUT, VALIDSOCK,STAT)

Arguments

SOCK1..SOCKN | A set of valid sockets
TIMEOUT | The time, in tenths of seconds, that the command will wait before returning
VALIDSOCK | Returns the number of a socket that is ready for reading (or ready for SOCKACCEPT in case of a server socket). If the command timed out, -1 is returned here
STAT | The status return

Note: TIMEOUT, VALIDSOCK and STAT are always required, and are not optional parameters.

Description

The SOCKWAIT command waits until a socket or set of sockets are ready for reading. It monitors a set of sockets and waits for one of them to have data available. In the case of server sockets (as created by SOCKSERV), the command returns when a connection is pending on the server socket and it can successfully be SOCKACCEPTed.

The second syntax of the command, where there the list of sockets is replaced with a –1, monitors all valid sockets created by the application. This reduces the logic required to write server applications that can accept many simultaneous clients.

Examples

SOCKSERV(0, 23) : Listen for socket 1 on port 23

@loop:

SOCKWAIT(-1,100000,VSOCK,STAT)

IF VSOCK=-1 GOTO @loop : TimeOut

IF VSOCK=0 THEN : New connection on server socket

SOCKFREE(n) : Find a free socket

SOCKACCEPT(0,n,STAT) : Accept the new connection

ELSE

GOSUB @HandleCommand

END IF

GOTO @loop


SQL

SQL ---------- Defines an SQL Access cursor

Type

SQL Access Command

Syntax

SQL(CUR$, SQL$, OFMT$, IFMT$, [CONN$], STAT)

Arguments

CUR$ | The cursor name by which it shall be known
SQL$ | The SQL statement associated with this cursor
OFMT$ | The format specification of the output data
IFMT$ | The format specification of the input data
CONN$ | The connection identifier. This argument is optional, it is only required in programs that use multiple concurrent connections. If it is not specified then the first connection in the list of connections will be assumed and if there is only one connection then this will be used. If the Connection Identifier is specified and that connection does not exist then an error status of 6 is returned.
STAT | The return status: -1 - Indicates an unspecific error. If this occurs, use the SQLERR statement to determine what that error is. 0 - No error 1 - Not logged on 2 - Cursor already exists 3 - Illegal Output Format Spec 4 - Illegal Intput Format Spec other - Driver specific code

Description

The SQL command declares an SQL Access cursor that encapsulates an SQL query. The cursor created by the SQL statement is used by the other SQL Access commands to access the SQL query associated with it. If the SQL query is parameterized, the query should be defined using question marks (the ? character) as the place-holder for each parameter. For example, for the SQL query:

SELECT FIELD1 FIELD2 WHERE FIELD3 > ? OR FIELD4 = ?

The two question marks indicate that two parameters will be supplied when the query is executed

The format of each input parameter to the SQL query is specified in the IFMT$ argument to the SQL statement. This is a format string very similar to a PACK format string and is made up of one of the following descriptors for each of the query's parameters:

Format
Descriptors

Description

Ax

Defines an 'x' character string

Nx.y

Defines an 'x' byte unsigned number, 'x' must be in the range 1-8 'y' declares a decimal scaling, as Business BASIC only supports integers, any decimal value in the SQL Access datasource is scaled by 10^y (10 to the power of y - can we use superscript in the actual document?) to prevent the loss of the decimal part. For numbers sent from U/BL to the SQL Access datasource, the value is divided by 10^y. In the reverse direction (data returned from the SQL Access datasource to U/BL) the value is multiplied by 10^y. For example:

Format N4.2 defines a 4 byte number with 2 decimal places.

If the datasource holds the value 1.23, the equivalent in U/BL would be 123.

Valid values for 'y' range from 1 to 10. If a value of 0 is used for 'y' the number is treated as an integer and no scaling is applied.

R

Row identifier

Sx.y

Defines an 'x' byte signed integer optionally of 'y' decimal places. For a description of the meaning and limits on 'x' an 'y' please refer to the description of the 'N' format.

Besides being used to define the format of the input parameters for the SQL query, the above format descriptors are used to define the format in which the query's results will be returned. This is achieved via the OFMT$ parameter to the SQL statement which specifies how each row of the query's results will be packaged when they are returned to the U/BL program. As for the IFMT$ parameter (which must include a format descriptor for each parameter to the query), OFMT$ must specify a format descriptor for each field returned by the query.

Note: The SQL statement defines the cursor that identifies the SQL query and specifies the format of the query's input parameters and output. The SQL statement does not run the query or return the results, the BASIC program must perform these tasks separately by using the EXEC and FETCH statements once the cursor has been defined.

Example

Thus a simple query of the type:

SELECT PRODNAME, PRICE, QTYOH FROM PRODUCTS WHERE PRODNO = ?

takes a single numeric input parameter and returns three fields, a product name, price and quantity. For example:

00100 REM Subroutine to find given product for processing

00110 REM

00120 REM Declare query

00130 LET SQL$="SELECT PRODNAME, PRICE, QTYOH, FROM PRODUCTS WHERE PRODNO=?"

00135 LET CONN$="BBISAMBOOKS"

00140 LET IFMT$="N4" : Input parameter 4-byte numeric (unsigned integer)

00150 LET OFMT$="A30,N4.2,S2.0" : 30 char string, 4 byte numeric (unsigned 2dp); 2 byte numeric (signed integer)

00160 SQL "GETPROD", SQL$, OFMT$, IFMT$, CONN$, STAT

00170 IF STAT<>0 THEN GOSUB @Process_SQL_Error

00180 REM

00190 REM Execute SQL Inquiry

00200 INPUT "Enter Product No.: ",PRODNO$

00210 EXEC "GETPROD", PRODNO$, STAT

00220 IF STAT<>0 THEN GOSUB @Process_SQL_Error

00230 REM

00240 REM Get (next) row of results

00250 FETCH "GETPROD", DETAILS$, STAT

00260 IF STAT=0 THEN

00270 GOSUB @Process_Results

00280 ELSE

00290 GOSUB @Check_Error_or_End

00300 END IF

00310 RETURN

See Also

DELCUR

EXEC

FETCH

SQLERR


SQLERR

SQLERR ---------- Returns SQL Access error information

Type

SQL Access Command

Syntax

SQLERR (ERRNO, MSG$ [, STATE$ [,STAT]])

Arguments

ERRNO | The native error number
MSG$ | The native error message
STATE$ | Retrieves the ODBC SQLSTATE
STAT | Optional status return.

Description

The SQLERR statement retrieves additional error information about the previously-executed SQL Access statement from the U/SQL server. The SQLERR statement can be used to provide additional information about the failure of any SQL Access statement that has occurred at the server. For those failures detected before U/BL submitted the request to the U/SQL server (those which have a specific error return defined for the statement), no additional information is available.

SQLERR retrieves the error number and associated message from the U/SQL Server. These depend on the particular U/SQL Server in use. Consult the documentation accompanying your U/SQL Server. In particular, the Error Messages, the Log File and How to Query it sections of Chapter 8 of the U/SQL Client-Server Configure and Use manual detail the format in which the error messages are returned.

In addition to returning the error in 'raw' format from the U/SQL Server, SQLERR can optionally return the error mapped onto an ODBC SQLSTATE. ODBC (Open DataBase Connectivity) is a standard allowing a common mechanism for different databases to be accessed by SQL-based tools. The SQLSTATE format provides an error return independent of the U/SQL server, so it is very useful for writing programs that are truly datasource independent. For an explanation of the SQLSTATE codes, refer to a suitable ODBC reference manual.

SQLERR returns the error number; message and SQLSTATE associated with the last executed SQL Access statement. In many circumstances, additional information for the error condition is available over and above the initial error message. In these situations, calling SQLERR repeatedly returns all of the available information a line at a time.

See Also

SQL


SQR

SQR ---------- Returns the square root of its argument

Type

U/BL function

Syntax

SQR(expr)

Arguments

expr

Any numeric expression.

Description

The SQR function finds the square root of its numeric argument, but the answer is truncated to an integer. Greater precision can be obtained by multiplying the expression by an even power of ten and interpreting the result accordingly.

Example

* list

00010 DIM X$[7]

00020 LET X$="D10.0,Z"

00030 FOR I=0 TO 16 STEP 2

00040 LET X$[5,5]=I/2

00050 PRINT USING X$,SQR(2*10^I)

00060 NEXT I

* run

1 1.4 1.41 1.4142 1.41421 1.414213 1.4142135

1.41421356


SRETURN

SRETURN ---------- Alternative version of _RETURN that does not require an underscore

Type

U/BL command and statement.

Syntax

SRETURN

Description

The SRETURN command is an alternative to the shared procedures' _RETURN command. As U/BL does not require special UBB statements to be preceded with an underscore, if a shared procedure is ENTERed and the environment variable BBNOUSCORE isn't set, or if it is set to Y, then the shared procedure's _RETURN statement(s) will have its underscore removed.

To prevent confusion with the traditional Business BASIC RETURN command, SRETURN can be used as an alternative. It performs exactly the same function as the _RETURN command.

Note: Regardless of BBNOUSCORE's setting, the only permitted ways of returning from a shared procedure are via either the _RETURN or SRETURN statements. The SRETURN command is really an underscore command, so if the environment variable BBNOUSCORE is set to N, this command will have to be preceded with an underscore, that is, _SRETURN.

Example

00010 SHARE("TEST")

00020 ENTRY("PRINTIT",1000,A$,A)

00030 INSTALL(STAT)

00040 IF STAT<>0 PRINT "Install error ",STAT

00050 END

01000 REM

01010 FOR I=1 TO N

01020 PRINT A$

01030 NEXT I

01040 LET A$=FILL$(66)

01050 LET N=N*2

01060 SRETURN

09999 END

See also

RETURN


SSTORE

SSTORE ---------- Stores current screen contents in a string variable

Type

U/BL Statement or Command.

Syntax

SSTORE(s$[,row,col,nrow,ncol])

Arguments

s$ | A string variable DIMensioned large enough to hold 2 bytes for each character position plus 8 bytes of header information , for example, for a full screen, s$ should be DIMensioned to 2*(24*80)+8, or 3848, bytes.
row | Store the section of the screen that starts at the specified row.
col | Store the section of the screen that starts at the specified column.
nrow | The number of rows to be stored.
ncol | The number of columns to be stored.

Description

The SSTORE command stores current screen contents in a string variable. If no co-ordinates are given the entire screen is stored. To ensure that the screen is up to date, the output buffer should be flushed with a STMA 8,5 statement before storing a screen.

If required the contents of the string can be unpicked. The first 8 bytes are a header, followed by a 2 byte combination for each row/col position. Under UNIX, these two bytes consist of an attribute character and then the character itself. On Windows, the two bytes are the character itself followed by its attribute.

As there is a difference in the ordering of the two bytes, screens SSTOREd under one type of operating system cannot normally be SLOADed under the other. However, the environment variable BBATTRIBORDER can be used to dictate which order was used by the operating system on which the program was originally developed. This means that programs do not have to be rewritten when transferring them between Windows and UNIX platforms.

Note: Windows and UNIX store the attribute/character information differently no matter what the setting of BBATTRIBORDER is. Windows stores the native operating system value, but UNIX stores a value which is only meaningful to Basic.

The header contains:

S[1]=row

S[2]=col

S[3]=nrow

S[4]=ncol

Example

:

00020 DIM S$[3848]

:

00150 _SSTORE(S$)

:

This stores the entire contents of the current screen in s$.

See also

$SCREEN_LOAD

$SCREEN_STORE

BBATTRIBORDER

SLOAD


STATCASE

STATCASE ---------- Retrieves the terminal control flag for automatically changing characters to upper case

Type

U/BL Statement.

Syntax

STATCASE num var

Arguments

num var

A numerical variable into which the value of the flag (0 or 1) is placed.

Description

The STATCASE statement retrieves the value of the UPPERCASE flag and stores it in the numeric variable. If the flag is set to 1, lower case characters are not automatically changed to upper case.

The STATCASE statement is equivalent to the STMA 5,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


STATCONTROL

STATCONTROL ---------- Retrieves the terminal control flag for retaining or discarding control characters

Type

U/BL Statement.

Syntax

STATCONTROL num var

Arguments

num var

A numeric variable into which the value of the flag (0 or 1) is placed.

Description

The STATCONTROL statement retrieves the value of the CONTROL flag and stores it in the numeric variable. If the flag is set to 1, control characters are not discarded, subject to the following rules:

  1. Control characters (except the current Backspace character or the current DEL character) are put into the buffer if there is auto unpending on every character or CONTROL (the STMA 6,2 statement) is set.

  2. Control characters that are either the current Backspace character or the DEL character are not treated as such, but instead are put into the input buffer if there is auto unpending on every character, or IKEY is disabled and CONTROL (STMA 6,2) is in effect.

The above rules also apply to the INPUT and INPUT USING statements, but not to @INPUT.

The STATCONTROL statement is equivalent to the STMA 5,2 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


STATECHO

STATECHO ---------- Retrieves the terminal control flag for character echo

Type

U/BL Statement.

Syntax

STATECHO num var

Arguments

num var

A numeric variable into which the value of the flag (0 or 1) is placed.

Description

The STATECHO statement retrieves the value of the ECHO flag, and stores it in the numeric variable. If the flag is set to 1, characters are not echoed to the port when received by U/BL.

The STATECHO statement is equivalent to the STMA 5,0 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


STATFILLC

STATFILLC ---------- Retrieves the terminal control flag for fill characters

Type

U/BL Statement.

Syntax

STATFILLC num var

Arguments

num var

A numeric variable into which the value of the flag (0 or 1) is placed.

Description

The STATFILLC statement retrieves the value of the FILL flag and stores it in the numeric variable:

  • If the flag is set to 1, then in a PRINT USING statement type D, E or F field, the mask characters to the left of the first significant digit are replaced by the fill character.

  • If the flag is set to 0, then the characters are left as in the buffer.

The default fill character (blank) always replaces mask characters to the left of the first significant digit, even if SETFILLC (STMA 6,7) is in effect.

Note: SWAP saves this value, and unSWAP restores it. Therefore, if the swapped-to program changes this value, it is restored to its prior value when the swapped-to program ENDs.

If the fill character is blank, the mask characters are always overwritten, even if NOFILLC (STMA 7,7) is in effect.

STATFILLC is equivalent to STMA 5,7.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


STATIKEY

STATIKEY ---------- Retrieves the terminal control flag for processing after IKEY interrupts

Type

U/BL Statement.

Syntax

STATIKEY num var

Arguments

num var

A numeric variable into which the value of the flag (0 or 1) is placed.

Description

The STATIKEY statement retrieves the value of the IKEY flag, and stores it in the numeric variable. If the flag is set to 1, an IKEY is not processed until this flag is set to 0, to allow interrupts to be disabled until they can be processed properly. If there are any pending IKEY interrupts, the SYS(26) statement yields a value 1. You can clear this flag and the pending interrupt with the RESETIKEY (STMA 8,3) statement.

The STATIKEY statement is equivalent to the STMA 5,5 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


STATUSMESSAGE

STATUSMESSAGE ---------- Changes status message at the bottom of the U/Gi screen

Type

U/BL Statement.

Syntax

STATUSMESSAGE(TEXT$ [, STAT] )

Arguments

TEXT$ | Specifies the text to be displayed on the status line
STAT | Optional error return.

Description

The STATUSMESSAGE command displays the message specified in the TEXT$ string, on U/Gi's status bar. Use the SETGUIOPT(21,"2,1", ER) statement to ensure that the status bar is displayed.

Applies To

U/Gi Status bar

Example

The following example program displays the text:

Error: the specified record is locked

in the status bar of the U/Gi Window:

REM Ensure U/Gi's status bar is visible

LET TOOLBARSTATE=21

SETGUIOPT(TOOLBARSTATE,"2,1", ER)

REM Display the error on status bar

STATUSMESSAGE("Error: the specified record is locked")

See Also

SETGUIOPT


STEP

STEP ---------- Executes and traces a specified number of program lines

Type

U/BL command.

Syntax

STEP [arg]

Arguments

arg

A numeric expression specifying the number of lines to step through.

Description

The STEP command is a debugging command which turns on TRACE and executes the specified number of lines in the program, starting from the current line. If the end of the program is reached, or the specified number of lines have been executed, the '*' prompt is redisplayed, and the TRACE switch is restored to its previous setting.

STEP 0 is a special form of the STEP command which resets the current position to the beginning of the program.

Example

* list

00010 PRINT "This is line 10"

00020 PRINT "This is line 20"

00030 LET X=X+1

00040 GOTO 00010

* step 0

* step

[00010] This is line 10 * step 6

[00020] This is line 20

[00030]

[00040] [goto]

[00010] This is line 10

[00020] This is line 20

[00030] * print x

2

See also

$N


STMA

STMA ---------- System calls to return or modify the program environment

Type

U/BL Statement.

Syntax

STMA type, argument

Arguments

type | A number designating the STMA call to make
arguments | The type and number of arguments depends on the system call. See STMA numbers below

Description

STMA calls examine or change a program's environment, manipulate dates, translate strings, generate errors, and set up a user program library. Each STMA call has its own type and number of arguments.

The following STMA statements are supported:

STMA 1 and 2 - Return/set terminal type and inter-program communication words

STMA 3 and 4 - Returns/sets program control keys and variables

STMA 5, 6, and 7 - Returns, sets and clears the value of a flag.

STMA 8 - Resets the internal stacks, the IKEY buffer, and flushes I/O buffers

STMA 9 - Returns the contents of system string variables

STMA 10 - Sets the four special characters for the CRM$ and UCM$ commands, and the default output file.

STMA 11 - Converts a Julian date to months, days , years

STMA 12 - Convert a date from months, days and years to Julian format

STMA 13 - Translates a string of characters, according to a user-defined table.

STMA 14 - Translates between upper and lower case, EBCDIC and ASCII, and 7 and 8 bit characters

STMA 15 - Compares two strings for a match.

STMA 19 - Generates errors.

STMA 20 - Declares a user program library for use from within an application.

STMA 21 - Provided for use by the SFORM.SL subroutine.


_STMA 9

_STMA 9 ------------ Returns the name of the currently running program

Type

U/BL Statement.

Syntax

_STMA 9,item,dest_var$,task

Arguments

item | A numeric constant specifying the information to be retrieved. Only the value 2 is supported.
dest_var$ | A string variable which returns the retrieved information.
task | This is an optional parameter which contains a task number. If it is not included, then information for the current task will be retrieved.

Description.

The _STMA 9,2 statement retrieves the name of the currently running program and returns it in the dest_var$ string variable. The maximum length of a program name is 12 bytes. If the program name is less then 12 bytes, then the trailing blanks after the program name are truncated from the name.

Example

The following program demonstrates the use of the _STMA 9,2 statement:

10 DIM PROG$(10)

20 STMA 9,2,PROG$

30 PRINT "The name of the current program is ";PROG$

40 END


STMA 1 and 2

STMA 1 and 2 --------- Return/set terminal type and inter-program communication words

Type

U/BL Statement.

Syntax

STMA 1, item, numeric_variable

STMA 2, item, numeric_expression

Description

The STMA 1 statement returns the terminal type or the value in the interprogram communication words. The STMA 2 statement sets them.

For a STMA 1 call, the numeric_variable parameter receives the value of the environment variable. In an STMA 2 call, numeric_expression is evaluated and the result placed in the appropriate environment variable. The item argument should be one of the following:

0 | Terminal type. See the GETTYPE and SETTYPE commands.
1 | Error code parsed between programs that use the SWAP and CHAIN commands
2 | Available single word for passing data between programs
3 | Second available single word for passing data between programs

If the terminal type is set within an STMA 2,0 statement, a PRINT @(-19)should follow to set the default terminal characteristics for the new type.

Items 1 to 3 are all available for data swapped between programs. Note that these only apply to programs that SWAP or CHAIN to each other. Normally, item 1 is used to pass error codes. All items are single words.

Examples

1. Retrieve the terminal type:

# stma 1,0,terminal_type

# ;terminal_type

8

2. Pass a number between programs:

# load"program1"

# list

0010 PRINT "This is program 1"

0020 INPUT "Enter a number to pass to program 2..",PASS_VALUE

0030 STMA 2,2,PASS_VALUE

0040 SWAP"Program2"

# load"program2"

# list

0010 PRINT "This is program 2"

0020 STMA 1,2,RECIEVED_VALUE

0030 PRINT "I've been given the value":RECEIVED_VALUE

#run"program1"

This is program 1

Enter a number to pass to program 2...452

This is program 2

I've been given the value 452


STMA 3 and 4

STMA 3 and 4 ---------- Returns/sets program control keys and variables

Type

U/BL Statement.

Syntax

STMA 3, item, numeric_variable

STMA 4, item, numeric_expression

Description

For an STMA 3 statement, the numeric_variable argument receives the appropriate value. In an STMA 4 statement, the appropriate key or variable is set to the value of numeric_expression. Usually, this is an ASCII value. The argument can be one of the following:

Item | Meaning
0 | Not used
1 | Line cancel key. This key cancels a line that is being typed. The default key is CTRL X (ASCII 24).
2 | Character delete echo. This is the character sent to the screen when a character is deleted. If it is set to a value of 128 or greater, the sequence (value-128), (space), (value-128) is echoed.
3 | Delete key. The default is DELETE (ASCII 127). STMA 4,3 has no effect as a command.
4 | Primary unpend key. Unpend keys are those keys that terminate an INPUT statement. They are never echoed on the console. The default primary unpend key is NEWLINE (ASCII 10). The setting of the unpend keys does not affect editing mode, only program running mode. They are reset whenever a RUN or RUN"program" is executed. Note that if the changed in a program, any other program swapped or chained to will also have the changed values.
5 | Secondary unpend key. (See 4 for more details on unpend keys.) The default secondary unpend key is LINE FEED (ASCII 13).The SYS(10) statement can be used to tell whether the primary or secondary unpend key was used to terminate the last input.
6 | Primary interrupt key. The default is ESC (ASCII 27).
7 | Secondary interrupt key. The default value is ASCII 255, which cannot be entered from the keyboard. If this key is to be used, it must be set to a CTRL character, with an ASCII value from 1 to 26, and it is activated by pressing CTRL C, and then the CTRL character. You can use SYS(10) to tell which interrupt key was pressed.
8 | Page width. This sets the number of characters allowed on a line at the terminal. The default is 80.
9 | Tab size. This set tab columns for output. All tabs are of equal length. The default setting is 14.
10 | The maximum number of characters allowed on input. The default is 132. If this variable is set to a positive number, an operator can only type that number of characters, with any additional characters being discarded and not echoed. If maximum number of characters is set to a negative number, the input automatically unpends when the absolute value of that number of characters has been typed.
11 | STMA 4,11,n performs in two separate ways, depending on whether the DGCOMP switch is set. If the switch is off, the it will reset the swap level to n (see the SYS(24) statement), provided n is less than the current value of SYS(24). If it is not less than the current value, the STMA is ignored.
12 | First-echoed character when a line cancel occurs. Usually ASCII 0 on a display terminal. When the line cancel key is pressed, two characters are normally echoed. On a printing terminal, the first is usually a backslash (ASCI 92) , and the second a NEWLINE (ASCII 10).
13 | Second-echoed character when a line cancel occurs. Usually ASCII 0 on a display terminal. See the explanation for 12.
14 | Pad character. On terminal with a slow line feed action, this character is sent to prevent any input before the cursor has reached the beginning of the line. Usually ASCII 0 on a display terminal.
15 | Number of pad characters to send. See 14 for description of pad character. Usually 0 on a display terminal.
16 | Unpend character 3.
17 | Unpend character 4.
18 | The default primary unpend key. This value will be copied into item 4 when the next RUN or RUN"program" command is issued, or a PRINT @(-19) is used to rest terminal characteristics.
19 | The default secondary unpend key. See 18 for description of unpend key. The value is copied into item 5. If both item 18 and 19 have a value of ASCII 255, the defaults for the terminal type are placed into items 4 and 5 when a PRINT @(-19) or RUN statement is issued.

The PRINT and INPUT statements can also change the values of the above items with @ statements. See the section on the PRINT statement for information about @ statements.

Examples

1. Adjusting the tab size

#list

0010 STMA 3,9,TABSIZE :get existing tab size

0020 STMA 4,9,5 :set a small tab size

0030 PRINT 1,2,3,4,5,6

0040 STMA 4,9,20 : set a large tab size

0050 PRINT 1,2,3,4,5,6

0060 STMA 4,9,TABSIZE :reset the default

2. Single character input

#list

0010 DIM X$[1]

0020 STMA 4,4,255 : disable primary unpend key

0030 STMA 4,5,255 : disable secondary unpend key

0040 INPUT USING "","",X$ : read a key

0050 PRINT ASC(X$) : print key's ASCII value

0060 IF X$<>"." THEN GOTO 30

0070 PRINT @(-19) : reset defaults

#run

65

90

49

30

113

46

These values correspond to the following keys being pressed: A Z 1 <F1> (produces two values) and .


STMA 5, 6 and 7

Type

U/BL Statement.

Syntax

STMA 5, flag, numeric_variable

STMA 6, flag

STMA 7, flag

Description

The STMA 5 statement returns the value of a flag (either one or zero). STMA 6 sets the flag to one, and STMA 7 clears it (sets it to zero). The numeric_variable parameter receives the value of the flag.

Flag | Meaning
0 | No echo. The default is off (echo). Input typed at the keyboard does not appear on the screen. Useful for entry of passwords.
1 | Allow both upper and lowercase characters to be entered. The default is on. If the flag is set, all input is folded to uppercase.
2 | Allow input of control characters. The default is off (no input of control characters). Normally, control characters other than line or character delete are ignored during input. When terminal type 6 is being used, a ^P must be typed before inputing any of the following control characters: ^C, ^O, ^P, ^Q, ^S, ^U, or ^T.
3 | Disable the column counter. The default is off (counter enabled).
4 | Disable messages. The default is to allow messages (off). Urgent messages can override this flag.
5 | Disable IKEY. The default is for IKEY to be enabled (off). If IKEY is pressed while the flag is set, the IKEY indicator will be set but no interrupt occurs. The SYS(26) statement tests whether the IKEY indicator is set. If it is, and STMA 7,5 is issued to clear this flag, an interrupt occurs immediately. See also the STMA 8,3 statement which clears the IKEY indicator.
6 | Suppress GOTO/GOSUB labels. The default is off (generate labels).
7 | Make fill character less fussy in a PRINT USING statement. The default is off . When this flag is clear, the fill character overwrites leading zeroes in Dw.d and Ew.d formats in PRINT USING statements. When the flag is set, the fill character overwrites all characters not directly used by those formats.
8 | No echo. The same as flag 0.
9 | Enable 8-bit LISTs. The default is for 7-bit lists (off). Usually, when a character with an ASCII value of more than 127 is LISTed, its value is output enclosed in angle brackets. If this flag is set, the character is output literally. Some output devices strip the high bits from characters; such a device displays the character that has an ASCII value of 128 less than the 8-bit character.

These flags can also be cleared or set with the PRINT USING or INPUT USING statements using the @(-18,flag) construct.


STMA 8

STMA 8 ---------- Resets the internal stacks, the IKEY buffer, and flushes I/O buffers

Type

U/BL Statement.

Syntax

STMA 8, item

Description

The STMA 8 statement resets the internal stacks, the IKEY buffer, and flushes I/O buffers.

The item parameter corresponds to one of the following:

Item | Meaning
0 | Reset both the FOR/NEXT and the GOSUB/RETURN stacks
1 | Reset the FOR/NEXT stack
2 | Reset the GOSUB/RETURN stack
3 | Reset the IKEY indicator
4 | Flush the input buffer
5 | Flush the output buffer. Not required where characters are output directly to the screen.


STMA 9

STMA 9 ---------- Returns the contents of system string variables

Type

U/BL Statement.

Syntax

STMA 9, item, string _variable

Description

The STMA 9 statement returns the contents of system string variables. The string_variable parameter is a dimensioned string that receives the value of item, as follows:

Item | Meaning
0 | Account name, as used to log on to the computer. The final digit of this name is the terminal type.
1 | Current directory name, including path.
2 | Current program name, as set by a SAVE, REPLACE or LOAD statement. The default is SCRATCH.
3 | The default output device name. This is the device to which utilities send their output when a /L switch is used.
4 | The system library directory.
5 | The system directory.
6 | The name of the previous program run.
7 | The current character settings of the four special CRAM characters, which are the four characters in addition to A-Z and 0-9 which the CRM$ and UCM$ commands recognize. The special characters are returned in the CRMCH$ string which must have been previously dimensioned to at least 4 characters.


STMA 10

STMA 10 ---------- Sets the four special characters for CRM$ and UCM$, and the default output file

Type

U/BL Statement.

Syntax

STMA 10, item,string

Description

The STMA 10 statement sets the four special characters for the CRM$ and UCM$ commands, and the default output file. The string argument can be either a dimensioned string variable or a quoted literal. The item argument can be one of the following:

Item | Meaning
0 | Special CRM$ characters. A string to be compressed should only contain the characters A-Z (uppercase only), 0-9, and four special characters. These special characters default to space, comma, hyphen, and period. Any other characters is replaced by the first special character. See CRM$ and UCM$.
1 | Default output file. This is the value returned by the STMA 9,3 statement and used by several utilities when the /L switch is used.

Examples

1. Set special characters for CRM$

#list 20

0020 STMA 10,0,"#$/*"

2. Set the output file so that a cross-reference goes to a file instead of the printer or screen

#stma 10,1,"myprog.lis"

#/table/l myprog.src

#stma 10,1,"@LPT"


STMA 11

STMA 11---------- Converts a Julian date to months, days , years

Type

U/BL Statement.

Syntax

STMA 11, julian_date, month, day, year

Arguments

julian_date | A numeric expression
month | A numeric variable receiving the appropriate value
date | A numeric variable receiving the appropriate value
year | A numeric variable receiving the appropriate value

Description

The STMA 11 statement converts a Julian date into its equivalent month, day, year representation. It is the inverse of the STMA 12 statement.

A Julian date is one which is expressed as a number of days from a given point. In the case of Business BASIC the given point against which all Julian dates are referenced is the start of 1968. The first of January 1968 is Julian date 1, the second of January 1968 is Julian date 2 and so forth.

The Julian date processing algorithms in U/BL are highly controlled by the environment variable BBJULIANFLAGS (and to a lesser extent BBDATEWINDOW). Dependant on the setting of this environment variable, the operation of any Julian date processing will alter in line with the settings of these environment variables. Refer to the documentation for BBJULIANFLAGS (and BBDATEWINDOW) for an explanation of the optional functionality.

Example

*list

00010 INPUT "Enter Julian date: ",J

00020 STMA 11,J,M,D,Y

00030 PRINT D;"/";M;"/";Y

00040 GOTO 00010

* run

Enter Julian date: 1

 1 / 1 / 68

Enter Julian date: 7517

 30 / 7 / 88

Enter Julian date:

See also

BBDATEWINDOW

BBEXTENSION

BBJULIANFLAGS

BBSDOSDATE

STMA 12

SYS(152)

$DATE$

$VDATE


STMA 12

STMA 12 ----------- Convert a date from months, days and years to Julian format

Type

U/BL Statement.

Syntax

STMA 12, Julian_date, month, day, year

Arguments

Julian_date | A numeric expression
month | A numeric variable receiving the appropriate value
date | A numeric variable receiving the appropriate value
year | A numeric variable receiving the appropriate value

Description

The STMA 12 statement converts a date in month, day, year representation into a Julian date. It is the inverse of the STMA 11 statement.

A Julian date is one which is expressed as a number of days from a given point. In the case of Business BASIC the given point against which all Julian dates are referenced is the start of 1968. The first of January 1968 is Julian date 1, the second of January 1968 is Julian date 2 and so forth.

The Julian date processing algorithms in U/BL are highly controlled by the environment variable BBJULIANFLAGS (and to a lesser extent BBDATEWINDOW). Dependent on the setting of this environment variable, the operation of any Julian date processing alters in line with the settings of these environment variables. Refer to the documentation for BBJULIANFLAGS (and BBDATEWINDOW) for an explanation of the optional functionality.

Example

* list

00010 INPUT "Enter day, month and year: ",D,M,Y

00020 STMA 12,J,M,D,Y

00030 PRINT J

00040 GOTO 00010

* run

Enter day, month and year: 1,1,68

 1

Enter day, month and year: 30,7,88

 7517

Enter day, month and year: 1,1,100

 11689

Enter day, month and year: _

See also

BBDATEWINDOW

BBEXTENSION

BBJULIANFLAGS

BBSDOSDATE

STMA 11

SYS(152)

$DATE$

$VDATE


STMA 13

STMA 13 ---------- Translate a string of characters, according to a user-defined table

Type

U/BL Statement.

Syntax

STMA 13,string_variable, table

Arguments

string_variable | A dimensioned string variable containing the characters to be translated
table | A string variable or literal of up to 256 characters.

Description

The STMA 13 statement translates a string of characters, according to a user-defined table.

The ASCII value of each character in the string_variable parameter is used to find the position of the table which replaces it. If the table is shorter than the ASCII value of the character, the last character in the table is used.


STMA 14

STMA 14 ---------- T ranslate between upper and lower case, EBCDIC and ASCII, and 7 and 8 bit characters

Type

U/BL Statement.

Syntax

STMA 14, string_variable, code

Description

The STMA 14 statement is a specialized case of the STMA 13 statement that translates between upper and lower case, EBCDIC and ASCII, and 7 and 8 bit characters. The string_variable parameter is a dimensioned string variable which contains the string to be translated, and which receives the resulting string. The code parameter is one of the following:

Code | Meaning
0 | Make upper case. All lowercase ASCII letters are folded to upper case. Other characters are not affected.
1 | Make EBCDIC. The string is converted from ASCII characters to EBCDIC characters.
2 | Make ASCII. The string is converted from EBCDIC characters to ASCII characters.
3 | Make lower case. All uppercase ASCII characters are folded to lowercase. Other characters are not affected.
4 | Clear 8-bit characters. Any character with the high bit set is changed to a space. Any character with the high bit clear os not affected. This leaves only normal ASCII characters (up to ASCII 127.)
5 | Clear 8-bit characters. Any character with the high bit set is changed to a space. Any character with the high bit clear os not affected. This leaves only normal ASCII characters (up to ASCII 127.)
6 | Clear 8th bit. Any characters with an ASCII value of more than 127 are converted to the character with a value 128 less.
7 | Set 8th bit. Any characters with an ASCII value of less than 127 (that is, normal ASCII characters) are converted to the character with a value 128 more.
8 | Clear 7-bit characters and clear 8th bit. Any characters with an ASCII value of less than 128 are converted to spaces. Any character with an ASCII value of 128 or greater is converted to the character with a value 128 less.

Example

# dim x$[50]

# x$="Be happy"

# stma 14,x$,0

# ;x$

BE HAPPY


STMA 15

STMA 15 ------------ Compare two strings for a match

Type

U/BL Statement.

Syntax

STMA 15, string, string, result

Description

The STMA 15 statement compares two strings for a match, where both strings are string variables or literals, and the result is a numeric variable, which receives zero if there is no match, or one if there is.


STMA 19

STMA 19 ---------- Generates errors

Type

U/BL Statement.

Syntax

STMA 19, error_number

Description

The STMA 19 statement generates errors. The error_number argument is the number of the error generated.

The error number is placed into the SYS(7) statement and an error interrupt is generated. If an ON ERR statement is active, it is executed; otherwise, a STOP if performed with the error_number printed.

See also

FORCERR


STMA 20

STMA 20 ---------- Declares a user program library for use from within an application

Type

U/BL Statement.

Syntax

STMA 20 [,channel]

Description

The STMA 20 statement declares a user program library for use from within an application. The optional channel argument is a numeric expression representing the channel number of an open library file.

Before a user program library can be used, the application must be told which file it is contained in. The file must first be OPENed in any appropriate mode, and then an STMA 20 statement issued. If another user program library is already in use, it is CLOSEd. The file OPEN on the specified channel is CLOSEd, and reOPENed as a system file, freeing the channel for reuse by user programs. Using STMA 20 without an argument CLOSEs any user program library in use.

Applications which do a lot of SWAPping or CHAINing between programs can benefit from using a program library. Programs LOAD more quickly from a library, because the file is always OPEN. An application package consisting of a number of programs may also be placed in a library to reduce the number of files to be distributed.

To place a series of programs in a library, use the PLB (Program Library Builder) utility; to access a program in the system library (ubblib), prefix the name with a hash symbol ('#'); to access a program in a user library, prefix the name with a percent sign ('%').

Example

If a user library called PAYROLL.PL has been built, and contains a number of programs linked together with a menu called PAYROLL.MN, a startup program might consist of:

00010 OPEN FILE[0,4],"PAYROLL.PL"

00020 STMA 20,0

00030 RUN"%PAYROLL"


STMA 21

STMA 21 ---------- A special statement for use by the SFORM.SL subroutine

Type

U/BL Statement.

Syntax

STMA 21,scrn$,f,xrow,xpos[,xcol[,xwid[,xflgs]]]

Arguments

scrn$ | A string variable which represents the contents of a CSM screen.
f | A numeric expression representing the relative field number (if negative), the field number (if between 0 and 100) or the row and field number in the format rrff (if greater than 100).
xrow | A numeric variable which receives the row number of the field when f is between 0 and 100.
xpos | A numeric variable which receives the position of the field in the row or -1 if the field does not exist.
xcol | A numeric variable which receives the column number of the field when f is between 0 and 100.
xflgs | A numeric variable which is set according to the attributes of the current field.

Description

The STMA 21 statement is provided for use by the SFORM.SL subroutine, which is a component of the CSM utility.


STMB 20

STMB 20 ---------- Performs a BYE statement

Type

U/BL Statement.

Syntax

STMB 20

Description

The STMB 20 statement has the same effect as the BYE command; it exits from Basic to its parent process.


STMC

STMC ---------- Makes calls to the operating system

Type

U/BL Statement.

Syntax

STMC,type,error,argument

Arguments

type | A number designating the STMC call to make
error | A numeric variable which receives an error code if the call fails. A result of zero or -1 indicates success.
argument | The type and number of arguments depends on the STMC call. See the help on individual STMC calls for full descriptions.

Description

STMC statements issue calls to the operating system. In some cases STMC statements duplicate or closely resemble normal Basic statements. This is usually because earlier versions of Business Basic lacked the normal statements. Because normal statements are more easily read and understood, they should be used in preference.

When a string variable is required to receive a value, the programmer should ensure that the variable is large enough to hold any value likely to be received. If the value received is longer than the variable then part of the user program may be overwritten with unpredictable results. A string variable supplied to receive a value should be null filled.

A string variable containing a value to be passed to the system call, or a string literal, should include a terminating null character, if program compatibility with Data General's Business BASIC is desired. This version of Basic appends this character itself in the appropriate STMC calls. Without this character, the system does not realize where the string ends, and erroneous results can occur.

The following STMC statements are supported:

STMC 0 - Create a contiguous file

STMC 1 - Creates a subdirectory (type DIR)

STMC 4, 33, 51 - Returns a status table

STMC 6,7 - Create a UDF-type file

STMC 8 - Deletes a file

STMC 9 - Changes the current directory

STMC 17 - Returns the current directory

STMC 21 - Creates a link file

STMC 22 - Sets a string length to zero

STMC 25 - Changes the name of a file

STMC 35 - Deletes a link file

STMC 36 - Flushes modified pages to disk

STMC 39-42,44 - OPEN a file in mode 7,2,0,3,5, or 0 respectively

STMC 52 - Create a contiguous file


STMC 0

STMC 0 ---------- Create a contiguous file

Type

U/BL Statement.

Syntax

STMC 0,error,filename$,sectors

Arguments

error | Returns the error code.
filename$ | A string variable or literal containing the name of the file to be created.
sectors | Contains a numeric expression ranging from 0 to 32767, representing the size of the file.

Description

The STMC 0 statement creates a contiguous file. The statement is identical to the STMC 52 statement.

The CREATE statement allows more control over the type of file created.

See also

CREATE

STMC 52


STMC 1

STMC 1 ---------- Creates a subdirectory (type DIR)

Type

U/BL Statement.

Syntax

STMC 1,error,directory$

Arguments

error | Returns the error code
directory$ | A string variable or literal containing the name of the directory to be created. The directory created has a type of DIR.

Description

The STMC 1 statement creates a subdirectory of type DIR.


STMC 4, 33, 51

STMC 4, STMC 33, STMC 51

Type

U/BL Statements.

Syntax

STMC 4,buffer$,channel

STMC 33,filename$,buffer$

STMC 51,filename$,buffer$

Arguments

buffer$ | The buffer used return the status table.
channel | The channel the file is opened on.
filename$ | The name of the file you want to return the status table for.

Description

The STMC 4 statement returns the status table in the buffer$ parameter for the file open on the specified channel.

The STMC 33 statement returns the status table in the buffer$ parameter for the file specified.

The STMC 51 statement returns the status table in the buffer$ parameter for the file specified. This is the same as the STMC 33 statement.

In U/BL Rev 5.00 and above the structure of the status table returned has been amended to support files larger than 4 GB, if the BBLARGEFILES environment variable is set to Y. The file length is specified in terms of a number of 512 byte blocks and a remainder. In revisions of U/BL prior to U/BL 5.00, the number of blocks was stored in 2 bytes. In U/BL Rev 5.00 and above, if Large File Support is enabled, another 4 bytes may be used for the high 4 bytes of the number of blocks.

Filename | 1 | 10
Extension | 11 | 12
Set to 64 | 13 | 14
Set to 64 | 15 | 16
Low 2 bytes of number of blocks | 17 | 18
Remainder | 19 | 20
Date last accessed | 23 | 24
Date last modified | 25 | 26
Time last modified | 27 | 28
High 4 bytes of number of blocks | 33 | 36

Example

The following example shows you how to get the size of a large file using the STMC 4 statement:

DIM B$[36],x$[6]

OPEN FILE[0,5],”TESTFILE”

STMC 4,ERROR,B$,0

IF ERROR<>-1 THEN STOP

LET X$=B$[33,36],B$[17,18]

LET FSIZE=ASC(X$)*512 + ASC(B$[19,20])

PRINT “SIZE = “;FSIZE


STMC 6, STMC 7

STMC 6, STMC 7 ---------- Create a UDF-type file

Type

U/BL Statement.

Syntax

STMC 6,error,filename$

STMC 7,error,filename$

Arguments

error | Returns the error code.
filename$ | A string variable or literal containing the name of the file to be created.

Description

The STMC 6 and STMC 7 statements perform exactly the same function. They create a UDF-type file with the user's default ACL, an element size of 4, and the default number of index levels. If more control is required, use the CREATE statement.

See also

CREATE


STMC 8

STMC 8 ---------- Deletes a file

Type

U/BL Statement

Syntax

STMC 8,error,filename$

Arguments

error | Returns the error code.
filename$ | A string variable or literal containing the name of the file to be deleted.

Description

The STMC 8 statement deletes files, however you are advised to use the DELETE statement for this purpose. The STMC 35 statement is provided explicitly to delete link files.

See also

DELETE

STMC 35


STMC 9

STMC 9 ---------- Changes the current directory

Type

U/BL Statement.

Syntax

STMC 9,error,directory$

Arguments

error | Returns the error code.
directory$ | A string variable or literal containing the name and path of the directory to change to.

Description

The STMC 9 statement changes the current directory. Read and execute access to the specified directory are required for this statement. The DIR statement exhibits the same functionality and should be used in preference to STMC 9.

See also

DIR

STMC 17


STMC 17

STMC 17 ---------- Returns the current directory

Type

U/BL Statement.

Syntax

STMC 17,error,directory$

Arguments

error | Returns the error code.
directory$ | An empty or null-filled string variable which receives the name and path of the current directory.

Description

The STMC 17 statement returns you to the current directory. The DIR statement performs the same function if an empty or null-filled string is supplied as an argument.

See also

DIR

STMC 9


STMC 21

STMC 21 ---------- Creates a link file

Type

U/BL Statement.

Syntax

STMC 21,error,linkname$,resolution$

Arguments

error | Returns the error code.
linkname$ | A string variables or literal which contains the name of the link file to be created.
resolution$ | A string variables or literal which contains the name and path of the file the link is to point to.

Description

The STMC 21 statement creates a link file. The STMC 35 statement deletes a link file.


STMC 22

STMC 22 ---------- Sets a string length to zero

Type

U/BL Statement.

Syntax

STMC 22,error,string$

Arguments

error | Returns the error code.
string$ | A string variable which is to be set to zero.

Description

The STMC 22 statement sets a string length to zero. For the sake of program clarity, It is preferable to use the statement:

LET string$=""


STMC 25

STMC 25 ---------- Changes the name of a file

Type

U/BL Statement.

Syntax

STMC 25,error,oldname,newname

Arguments

error | Returns the error code.
oldname | A string variables or literal which contains the existing name of the file.
newname | A string variables or literal which contains the new name the file is to be changed to.

Description

The STMC 25 statement changes the name of a file. The RENAME statement performs the same functionality and should be used in preference.

Neither STMC 25 or RENAME should be used for SAVE files for reasons explained under the RENAME statement.

See also

RENAME


STMC 35

STMC 35 ---------- Deletes a link file

Type

U/BL Statement.

Syntax

STMC 35,error,linkname$

Arguments

error | Returns the error code.
linkname$ | A string variable or literal containing the name of a link file to be deleted.

Description

The STMC 35 command deletes the specified file only if it is a link file. The STMC 21 statement creates a link file.


STMC 36

STMC 36 ---------- Flushes modified pages to disk

Type

U/BL Statement.

Syntax

STMC 36,error,channel

Arguments

error | Returns the error code.
channel | The Basic channel number used to OPEN the file.

Description

The STMC 36 statement updates the file on disk. File I/O statements which modify the contents of a file do not actually write the changes to disk immediately, but let the operating system do so at its own pace. A system crash can result in the file being left in an inconsistent state.

Under SCO UNIX, the STMC 36 statement issues a sync command which schedules all of the data in the system's memory to be written out. Refer to the operating system's documentation on sync for further details.

On other UNIX based platforms, the STMC 36 statement ensures that the data that is associated with the given channel is written to the disk. Control is not returned to the program until all of the data has been written out. Refer to the operating system's documentation on fsync for further details.

Note: The STMC 36 statement does not work on Windows based platforms if SmartDrive is installed.


STMC 39-42, STMC 44

STMC 39-42, STMC 44 ---------- OPENs files in modes 2,0,3,5, or 0 respectively

Type

U/BL Statement.

Syntax

Format 2: STMC 39,error,filename$,mask,channel

Format 3: STMC 40,error,filename$,mask,channel

Format 4: STMC 41,error,filename$,mask,channel

Format 5: STMC 42,error,filename$,mask,channel

Format 6: STMC 44,error,filename$,mask,channel

Arguments

error | Returns the error code.
filename$ | A string variable or literal containing the name of the file to OPEN.
mask | A numeric expression whose value is ignored.
channel | A numeric expression whose value determines the Basic channel number on which the file is OPENed.

Description

The STMC 39 statement exclusively OPENs an existing file for appending to.

The STMC 40 statement exclusively OPENs a file for I/O. If the file is not found in the current directory or on the searchlist, it is created.

The STMC 41 statement OPENs an existing file for input.

The STMC 42 statement OPENs an existing file for I/O.

The STMC 44 statement is the same as STMC 40.

Modes 2, 0, 3, 5 and 0 correspond to STMC 39-42 and 44, respectively. STMC 40 and STMC 44 differ from Data General's Business BASIC, where both statements require that the file already exist, and STMC 44 OPENs a file in shared mode.

The OPEN statement should be used in preference to these STMC statements.


STMC 52

STMC 52 ---------- Create a contiguous file

Type

U/BL Statement.

Syntax

STMC 52,error,filename$,sectors

Arguments

error | Returns the error code.
filename$ | A string variable or literal containing the name of the file to be created.
sectors | Contains a numeric expression ranging from 0 to 32767, representing the size of the file.

Description

The STMC 52 statement creates a contiguous file. The statement is identical to the STMC 0 statement.

The CREATE statement allows more control over the type of file created.

See also

CREATE

STMC 0


STME

STME ------------ Make operating system calls

Type

U/BL Statement.

Syntax

STME,type,error,argument

Arguments

type | A number designating the STME call to make
error | A numeric variable which receives an error code if the call fails. A result of zero or -1 indicates success.
argument | The type and number of arguments depends on the STME call. See the help on individual STME calls for full descriptions.

Description

The STME statement like the STMC statement, issues calls to the operating system. The same comments on null filling of strings which receive values, and null terminating characters for strings which pass values, apply. Most STME calls have no equivalent statements in this version of Basic.

The following STME statements are supported:

STME 0 - Returns the files in a directory

STME 1 - Returns the user name of the current process

STME 2 - Returns the PID number of the current process

STME 4 - Returns a complete pathname for a file

STME 6,7 - Return file status information

STME 8,9 - Create a file with specified date and time stamps

STME 10 - Returns a complete pathname for a file

STME 11 - Resolves a link file

STME 16 - Sends a message

STME 19 - Executes an external program

STME 27 - Sets up a string for editing, and places the cursor within it.


STME 0

STME 0 ---------- Returns the files in a directory

Type

U/BL Statement.

Syntax

STME 0,error,channel,pointer,filename$,template$

Arguments

error | Error code returned.
channel | A numeric expression representing the Basic channel number used to OPEN a directory
pointer | A numeric variable used by the operating system to determine where in the directory to start searching for the next filename. The first time STME 0 is used for a particular directory, pointer should be set to zero. On subsequent uses, the value of pointer should be left unchanged.
filename$ | A null filled string which receives the next suitable filename
template$ | A string which contains a pattern which the filename returned must match. Note that template$ is case sensitive, that is, "aaa+" is different to "AAA+".

Description

On DOS based systems, directories cannot be OPENed. Therefore the STME 0 statement works on the parent directory of the file which has been OPENed on the specified channel.

The first time STME 0 is used for a particular directory, the pointer argument should be set to zero. On subsequent uses, the value of the pointer argument should be left unchanged. The operating system uses the pointer argument to determine where in the directory to start searching for the next filename. The template$ argument can contain the wildcard characters '+', '-' and '*'. A template$ containing only '+' can be used to return all filenames.

The STME 0 statement is fully supported under Windows, but in a slightly different manner as under UNIX U/BL or the original Business BASICs. The difference in implementation is that instead of being able to OPEN a directory, U/BL for Windows must OPEN a file in the directory and use STME 0 against the channel that file is OPEN on. For example, instead of using:

10 OPEN FILE[CHAN,5],"DIRECTORY"

20 STME 0,ER,CHAN,PTR,NXT_FILE$,"+"

use:

10 OPEN FILE[CHAN,0],"DIRECTORY:STME0.WRK"

20 STME 0,ER,CHAN,PTR,NXT_FILE$,"+"

This is because Windows does not allow directories to be opened directly in the same way as it does files.


STME 1

STME 1 ---------- Returns the user name of the current process

Type

U/BL Statement.

Syntax

STME 1,error,username$

Argument

error | Returns the error code
username$ | A null filled string variable which receives the user name.

Description

The STME 1 statement returns the user name of the current process.


STME 2

STME 2 ---------- Returns the PID number of the current process

Type

U/BL Statement.

Syntax

STME 2,error,pid

Arguments

error | Returns the error code.
pid | A numeric variable which receives the PID.

Description

The STME 2 statement uses ?PNAME to retrieve the PID number of the current process.


STME 4

STME 4 ---------- Returns a complete pathname for a file

Type

U/BL Statement.

Syntax

STME 4,error,filename$,path$

Arguments

error | Returns the error code.
filename$ | A string representing the file.
path$ | An empty or null-filled string variable which receives the value of the path.

Description

The STME 4 statement returns a complete pathname for a file. If the file is a link file, it is resolved, and the path of the file it points to is returned. The STME 10 statement also returns a pathname but does so for an open file.

See also

STME 10


STME 5,6,7

STME 5,6,7 ---------- Return file status information

Type

U/BL statement.

Syntax

STME 5,error,fstat$,channel

STME 6,error,filename$,fstat$

STME 7,error,filename$,fstat$

Arguments

error | Returns the error code.
fstat$ | A string variable of at least 46 bytes long which receives the packet of file status information.
channel | The Basic channel used to OPEN the file.
filename$ | A string containing the name of the file.

Description

The STME 5, STME 6 and STME 7 statements return file status information. The STME 5 statement require the file to be OPEN and the channel number to be specified. The STME 6 statement requires the file name. The STME 7 statement is identical to STME 6 except that it resolves a link file.

The STME 5, STME 6 and STME 7 statements all return the same file status packet information:

File Type, 10, 20 or 64 | 1 | 2
Set to -1 | 3 | 6
Undefined | 7 | 16
Date of creation | 17 | 18
Time of creation | 19 | 20
Date last accessed | 21 | 22
Time last accessed | 23 | 24
Date last modified | 25 | 26
Time last modified | 27 | 28
Undefined | 29 | 34
Low 4 bytes of File Size | 35 | 38
Address / Inode | 39 | 42
High 4 bytes of File Size | 43 | 46

In U/BL Rev 5.00 and above, if Large File Support is enabled (by setting the BBLARGEFILES environment variable to Y), the File Size can be stored in 8 bytes, the low order 4 bytes will remain at position 35 – 38 in the file status packet, the high order 4 bytes will be stored at position 43 – 46 in the file status packet.

Example

DIM F$[50],X$[8]

DIM B$[46]

LET B$=FILL$(0)

INPUT "File :",F$

OPEN FILE[0,5],F$

STME 5,ERROR,B$,0

IF ERROR<>-1 THEN STOP

LET X$=B$[43,46],B$[35,38]

LET LENF=ASC(X$)

PRINT "length=";LENF


STME 8,9

STME 8,9 ---------- Create a file with specified date and time stamps

Type

U/BL Statement.

Syntax

STME 8,error,filename$,sectors,date$

STME 9,error,filename$,date$

Arguments

error

Returns the error code

filename$

A string containing the name of the file to create

sectors

A numeric expression which represents the size of the file.

date$

A string of 12 bytes formatted as follows:

Bytes | Meaning
1-2 | The date the file was created, in DG Julian format. See STMA 11 and STMA 12 for an explanation of this format.
3-4 | The time the file was created, represented as half the number of seconds since midnight.
5-8 | The date and time of the last file access, in the same format as the creation date and time.
9-12 | The date and time of the last modification, in the same format as above.

All numbers should be placed in the string with the CHR$ function or a similar method.

Description

The STME 8 statement creates a contiguous file, while the STME 9 statement does not.


STME 10

STME 10 ---------- Returns a complete pathname for a file

Type

U/BL Statement.

Syntax

STME 10,error,path$,channel

Arguments

error | Returns the error code.
path$ | An empty or null filled string variable which receives the value of the path.
channel | A numeric expression representing the Basic channel used when the file was OPENed.

Description

The STME 10 statement returns a complete pathname for a file. The STME 4 statement also returns a pathname but does so using a filename.

See also

BBSTME10

STME 4


STME 11

STME 11 ---------- Resolves a link file

Type

U/BL Statement.

Syntax

STME 11,error,link$,resolution$

Arguments

error | Returns the error code.
link$ | A string containing the name of a link file
resolution$ | An empty or null filled string variable which receives the name of the resolution file.

Description

The STME 11 statement resolves a link file.


STME 16

STME 16 ---------- Sends a message to a specified console name

Type

U/BL Statement.

Syntax

STME 16,error,console$,message$

Arguments

error | Returns the error code.
console$ | A string which contains a console name.
message$ | A string containing the message to be sent.

Description

The STME 16 statement sends a message to a specified console name.

UNIX based platforms

On UNIX based platforms, the STME 16 statement sends the message to the process controlling the specified terminal number. The console$ parameter is set to a string made up of the text "@CON" and the terminal number to which the message is to be sent.

Basic determines which terminal to send the message to by looking up the number specified in console$ in the file specified by the environment variable BBTTYS.

Note: The console$ parameter must always begin with either "@CON" or "@con", and end with a terminal number.

The error parameter is set to -1 if the call was successful, or 21 if it could not access the specified terminal.

Example

If the BBTTYS file contains the following list of terminals:

/dev/ttytc01 1

/dev/ttytc02 2

/dev/ttytc03 3

and you want to send a message to terminal 2 (/dev/ttytc02 in the BBTTYS file), you could use the following:

00010 DIM CONSOLE$[6]

00020 LET ER=0 \ CONSOLE$="@CON2"

00030 STME 16,ERROR,CONSOLE$,"Please log off - System closing"

When RUN, this program sends the message to the process controlling the device /dev/ttytc02. The message appears as:

From Pid n : Please log off - System closing

where n is your controlling process' number.


STME 19

STME 19 ---------- Executes an external program

Type

U/BL Statement.

Syntax

STME 19,error,program$,buffer$

Arguments

error | Returns the error code.
program$ | A string containing the name of a program to execute.
buffer$ | A string the contents of which are passed to the program as an initial IPC.

Description

If the STME 19 statement is used to shell to the operating system, then the program$ argument should contain ":CLI.PR" and the buffer$ argument the CLI command line, which may include several commands separated by semicolons. If the buffer$ argument is empty, the CLI is invoked and control does not return until BYE is typed or CLI terminates for an abnormal reason.

The Basic process is blocked while the program executed by STME 19 is running.

See also

$EXECUTE


STME 27

STME 27 ---------- Sets up a string for editing, and places the cursor within it

Type

U/BL Statement.

Syntax

STME 27,error,string$,cursor_pos

Arguments

error | Returns the error code.
string$ | A string variable the contents of which are possibly to be edited
cursor_pos | A numeric expression. If cursor_pos is set to zero, the input field will initially be blank, but the contents of the string will appear if ^A is typed at the keyboard.

Description

The STME 27 statement sets up a string so that it can be edited after an INPUT statement.

If the environment variable BBEXTENSION is set to include B32, then if cursor_pos is set to one or more, the contents of string$ are displayed at the INPUT statement, and the cursor is placed on the character specified.

If BBEXTENSION does not include B32, then cursor_pos can be set to either zero (see above), one or two. If set to one, then the contents of string$ are displayed at the INPUT statement, and the cursor is placed on the first character. If set to two, then the contents of string$ are displayed at the INPUT statement, and the cursor is placed on the last character.

A cursor_pos which is greater than the length of the string results in the cursor being placed at the end of the string.

See also

GET27BUF

Appendix J - U/BL Line Editing Commands.


STOP

STOP ---------- Halts program execution

Type

U/BL statement.

Syntax

STOP

Description

The STOP statement ends a program, displaying the message "STOP at xxxxx", where xxxxx is the program line number. It is usually used for debugging or because of an error condition.

If the program has been SWAPped to, and finishes because an END statement has been encountered, it returns control to the previous level. If it finishes because of a STOP statement, however, control stays at the current level and returns to keyboard mode, that is, the '*' prompt. The current push level will be displayed with the '*' prompt if it is greater than zero.

A CON statement can be issued after a program STOPs to resume execution.

The STOP statement can follow ON ERR or ON IKEY statements, but in the former case it only replaces the error message with its own, which is not usually desirable, and in the latter case, to STOP a program is the default anyway.

Example

* list

00010 PRINT "this is line 10"

00020 STOP

00030 PRINT "this is line 30"

* run

this is line 10

STOP at 20

See also

CON

END


STRPOS

STRPOS ----------- Finds the starting position of a substring in a string

Type

U/BL command and statement.

Syntax

STRPOS position, long$,short$ [,start, increment]

Arguments

position | A numeric variable which receives the position of short$ in long$.
long$ | A string expression within which short$ may occur
short$ | A string expression which STRPOS attempts to find in long$
start | The first byte at which STRPOS begins searching long$. If start is omitted, the search begins at the first character of long$.
increment | The increment value for the long$ pointer after each comparison with short$. If an increment is not specified, it defaults to one.

Description

The STRPOS command is used to find a substring at specific places in another string. It begins searching the long string for the substring at the position specified by the start_pos parameter, and if there is no match at the point, it increments its position by the value specified in the increment parameter and compares again. The STRPOS command continues to compare and increment until a match is found or the end of the string is reached.

If the increment parameter is set to one, the STRPOS command examines every byte of the string for possible matches with the substring. This makes it equivalent to the POS function.

If the substring is found, the position variable receives the position of the first matching character. If the substring is not found, the position variable is set to zero.

Example

* list

00010 DIM MONTH$[108],X$[9]

00020 LET MONTH$="JANUARY FEBRUARY MARCH APRIL "

00025 LET MONTH$[0]="MAY JUNE JULY AUGUST "

00030 LET MONTH$[0]="SEPTEMBEROCTOBER NOVEMBER DECEMBER "

00040 INPUT "Enter the abbreviation for a month...",X$

00050 IF X$="" THEN GOTO 00150

00055 STMA 14,X$,0 : MAKE X$ UPPERCASE

00060 STRPOS P,MONTH$,X$,1,9

00070 IF P THEN

00080 PRINT "Your month in full is ";MONTH$[P,P+8]

00090 ELSE

00100 PRINT "No month has that abbreviation"

00110 END IF

00120 INPUT "Enter the abbreviation for another month...",X$

00130 GOTO 00050

00150 END

* run

Enter the abbreviation for a month...sep

Your month in full is SEPTEMBER

Enter the abbreviation for a month...tember

No month has that abbreviation

Enter the abbreviation for a month...m

Your month in full is MARCH

Enter the abbreviation for a month...

See also

POS

SCANUNTIL

SCANWHILE


STRMATCH

STRMATCH ---------- To compare two strings for a match

Type

U/BL Statement.

Syntax

STRMATCH string1,string2,result

Arguments

string1 | A string variable or string literal which may contain special wildcard characters, for example, a dash or an asterisk.
string2 | A string variable or string literal
results | A numeric variable that is set to 1 if the two strings match, or to 0 if they do not match

Description

The STRMATCH statement makes a comparison between two strings for a match. The first string can contain wildcard characters. If the strings match, the result variable is set to 1; if they do not match, it is set to 0.

The wildcard characters in the first string have a special meaning when STRMATCH is comparing the strings. The dash '-' matches any number of characters and the asterisk '*' matches any single character in the same location as the asterisk.

STRMATCH is used primarily for manipulation of file names in the Data General environment, but it can have some use with file names in the U/BL environment. However, you must pay particular attention to the use of the dash and the asterisk wildcards.

Note: STRMATCH has been implemented in the way Technical Analysis Corporation (TAC) first defined it, and not in the Data General method of implementation.

The STRMATCH statement is equivalent to the STMA 15 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program demonstrates the use of the STRMATCH statement:

10 DIM X$ (20)

20 X$="-ABC-"

30 STRMATCH X$, "123ABC" ,X \ GOSUB 200 :match

40 STRMATCH X$, "123ABCXYZ" ,X \ GOTO 200 :match

50 STRMATCH X$, "123ABCXYZ." ,X \ GOSUB 200 :match

60 STRMATCH X$, "123ABCXYZ" ,X \ GOSUB 200 :match

70 STRMATCH "-ABC*" , "123ABCXYZ.567" ,X \ GOSUB 200 :no match

80 STRMATCH "ABC-.-" , "123ABCXYZ" ,X \ GOSUB 200 :no match

90 STRMATCH "*ABC*E" , "XABCDE" ,X \ GOSUB 200 :match

100 STRMATCH "*ABC.-" , "XABC.123" ,X \ GOSUB 200 :match

110 END

200 : ROUTINE TO PRINT STRMATCH VARIABLE

  :

  : X=1 IF STRMATCH ELSE X=0

  :

  IF X THEN PRINT "MATCH" ELSE PRINT "NO MATCH"

  RETURN

When executed, this program produces the output shown below:

MATCH

MATCH

MATCH

MATCH

NO MATCH

NO MATCH

MATCH

MATCH


SUNLOCK

SUNLOCK ---------- Unlocks records locked using the SLOCK statement

Type

U/BL Statement.

Syntax

SUNLOCK

SUNLOCK FILE(channel)

SUNLOCK FILE(channel,recnum)

Arguments

channel | A numeric expression specifying a channel number on which a file is opened
recnum | A numeric variable that specifies the starting record number to unlock

Description

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

The SUNLOCK statement unlocks records that have been locked with SLOCK, BYTELOCK, or AUTOLOCK FILE.

The SLOCK statement causes an entry to be put into the U/BL lock table. The entry in the lock table identifies the file, the starting byte, and the number of bytes. When a record is unlocked, the entry is removed. The SLOCK table in U/BL is of finite length. The length of the table is specified during system generation in the 102 line of the U/BL configuration file.

Use SUNLOCK to unlock the records when they no longer need to be locked.

There are three forms of SUNLOCK:

  • Form 1 contains no arguments, and unlocks every record that was locked.

  • Form 2 unlocks all records for the file opened on the specified channel.

  • Form 3 unlocks a specific record for a file.

If a record that is specified using SUNLOCK is not locked, then the SUNLOCK does nothing. Nothing is unlocked and there is no error. If a record specified in an SUNLOCK is locked, but by another task, a run-time error (#42) occurs.

As SUNLOCK deletes a lock entry in the table when any record is unlocked, every other record that was locked by the same SLOCK statement is unlocked. If records 25-30 are locked with SLOCK, and record 28 is later unlocked with SUNLOCK, records 25, 26, 27, 29, 30 are unlocked as well.

Note: The functionality provided by the environment variable setting BBSLOCK=N is not supported due to current Windows restrictions.

Example

See the example in SLOCK. The examples shown below do not comprise a program.

100 RN=3

110 SUNLOCK FILE (0, RN) :UNLOCK RECORD 3

120 SUNLOCK :UNLOCK ALL RECORDS IN ALL FILES


SWAP

SWAP ----------- Load and execute another program, and then return

Type

U/BL command or statement.

Syntax

[SWAP] program [THEN CON]

[SWAP] program [THEN GOTO line_no]

Arguments

program | A DIMensioned string variable or sub-string, or string literal, containing the name of a SAVEd Basic program.
line_no | A line number in the program being SWAPped to

Description

The SWAP command LOADs and executes a program, but it doesn't clear any existing program from memory. When the SWAPped to program ENDs, control returns to the current program.

The THEN options for SWAP work just like the equivalent operations for the CHAIN command. The CON command begins running the newly LOADed program from the point at which it STOPped before it was last SAVEd, while GOTO line_no begins running the program at the specified line number. If no THEN clause is used, SWAP runs a program from the beginning.

The word SWAP is optional if Basic is in keyboard mode, that is, at the '*' prompt, and if the program name is a quoted string literal, but it must be used for a program name which is a string variable or from within a program.

A maximum of 20 SWAP levels is allowed. If a "SWAPped to" program returns to the '*' prompt, the current SWAP level is displayed next to the '*' prompt, for example, 2*.

Example

* list

00010 PRINT "This is program 1"

00020 SWAP "PROG2"

00030 PRINT "This is program 1 again"

* "PROG2

This is program 2

* run

This is program 1

This is program 2

This is program 1 again

See also

BLOCK_READ

BLOCK_WRITE

CHAIN

RUN


SYS

SYS ---------- Returns system information and Basic statistics

Type

U/BL function

Syntax

SYS(num)

Arguments

num

A numeric expression indicating what information is required

Description

The SYS(1-31) functions are the same as those provided by Data General's Business BASIC.

U/BL also provides additional SYS functions for statistics and other information. These are extra SYS functions to those provided by Data General's Business BASIC. All previously existing SYS functions work in the same way.

Note: The basic functionality of the SYS functions is described below. Where additional information is provided for certain functions, then you can click on the relevant hyperlink to view this information.

SYS returns the information indicated by the num parameter, where the num parameter is one of the following:

0 | Seconds elapsed since midnight
1 | Day of the month (1-31)
2 | Month of the year (1-12)
3 | Year in four digits, for example, 1992
4 | Console number
5 | CPU time used (tenths of a sec)
7 | Error code for the last error
8 | Last channel number referenced
9 | PID number
10 | Alternate IKEY/UNPEND flag
12 | Seconds since the last minute
13 | Minutes since the last hour
14 | Hours since midnight
16 | User status word 2 - hard coded value of 6656
17 | Program length in bytes
18 | Data length in bytes
19 | Maximum program/data length
20 | Line of last error or IKEY
22 | Time left after TINPUT/INPUT
24 | Push level
26 | IKEY status flag
27 | Time of day in the format hhmmss
28 | Current date in the format MMDDYY
29 | A unique number in a series (may need BBRDOS)
30 | System status. See the entry for SYS(30)
31 | Operating system error code
34 | For SuperDOS emulation, SYS(34) returns the current precision: 2 - for double precision 3 - for triple precision 4 - for quadruple precision If running without the SuperDOS extensions, SYS(34) returns the next channel number.
38 | User's security level (BBSLEVEL) Otherwise unsupported
46 | Size of #COMM$
49 | Under SuperDOS emulation this represents the number of BBASIC channels. Otherwise it is unsupported
98 | No longer supported
99 | The operating system: 0 - for UNIX 4 - for Windows NT 5 - for Windows 95
104 | No longer supported
109 | The pid of U/BL
152 | The current Julian date
153 | Current/last line number
154 | Line number of the last GOTO
155 | Line number the GOTO jumped to
156 | Line number of the previous GOTO
157 | Line number previous GOTO jumped to
158 | Line number of active ON ERR
159 | Line number of active ON IKEY
160 | The maximum size of the GOSUB stack
161 | Old banner - Unique installation number New banner - Unique license number from banner
163 | The row number the cursor is at
164 | The column number of the cursor
165 | Last operating system internal error number
166 | Number of allowable U/BL users on the current banner
167 | Number of allowable U/SQL users on the current banner
168 | Last U/BL windowing error code
170 | Value of the last unpend key
171 | Major revision
172 | Minor revision
173 | Hotfix
200 | Physical line number of the last error
201 | Physical line number of the current line
998 | No longer supported
999 | No longer supported
1000 | Size of user configurable memory in use
1001 | Reserved
1002 | No longer supported
1003 | No longer supported
2000 | Year 2000 compliance flag
2028 | Current date in the format MMDDCCYY

Examples

* print "Today is";sys(1);"/";sys(2);"/";sys(3)

Today is 16 / 7 / 1992

* print "The time is";sys(14);":";sys(13);":";"sys(12)

The time is 11 : 50 : 21

* dim x$[20]

* x$=$date$(sys(152),0,3)

* print "Another way to get the date - it's ";x$

Another way to get the date - it's 16-July-92

See also

BBDATEWINDOW | BBEXTENSION | BBJULIANFLAGS
BBRDOS | BBSLEVEL | GOSUB
GOTO | INPUT | ON ERROR
ON IKEY | STMA 4 | SWAP
SYS(29) | SYS(30) | SYS(34)
SYS(99) | SYS(152) | SYS(161)
SYS(165) | SYS(166) | SYS(167)
SYS(170) | SYS(200) | SYS(2000)
SYS(2028) | TINPUT |


SYS(29)

SYS(29) ---------- Returns a unique number in a series

Type

U/BL function

Syntax

SYS(29)

Description

If the BBRDOS environment variable is set to Y, then the SYS(29) function returns a unique number that is determined by the number of times the SYS(29) function has been accessed by all jobs.

If BBRDOS environment variable is not set, or if it is set to N, then the SYS(29) function returns the process PID number plus a multiple of 1000. That multiple is determined by the number of times that the SYS(29) function has been accessed by that process.


SYS(30)

SYS(30) ---------- Provides system status information

Type

U/BL function

Syntax

SYS(30)

Description

The system status function SYS(30) returns a bit-mapped flag, with bits having the following significance:

Windows, UNIX and DOS based platforms

Bit | Representation | Indicates | When set
1 | 1 (2^0) | Double Precision | BBPRECISION=4
2 | 2 (2^1) | Triple Precision | BBPRECISION=6
3 | 4 (2^2) | Quad Precision | BBPRECISION=8
12 | 2048 (2^11) | U/BL | When not AOS/VS or RDOS
13 | 4096 (2^12) | U/BL with Large File Support | When BBLARGEFILES=Y and BBPRECISION=Y and platform supports large files
17 | 65536 (2^16) | Op. Sys. is UNIX | On UNIX
18 | 131072 (2^17) | Op. Sys. is DOS | On a DOS system
19 | 262144 (2^18) | Op. Sys. is LAN | On a Network
20 | 524288 (2^19) | Op. Sys. is VMS | On VAX
21 | 1048576 (2^20) | U/BL invoked with -g | U/BL invoked with the '-g' (GUI) switch
22 | 2097152 (2^21) | UBB under Windows | When using UBB under Windows
23 | 4194304 (2^22) | U/BL | When running U/BL
24 | 8388608 (2^23) |  | On Windows NT and Windows 2000
25 | 16777216 (2^24) |  | On Windows 95/98

An Example of the use of the SYS(30) statement

The SYS(30) statement can be used to indicate whether U/BL has been invoked with Large File Support (LFS). If bit 13 (4096) is set then U/BL is running on a platform that supports large files and BBLARGEFILES=Y and BBPRECISION=8. This allows the U/BL programmer to write code for LFS and non-LFS operation.

The following example code shows the use of SYS(30) to detect large file support:

IF AND(SYS(30),4096) THEN

PRINT “Large Files Supported”

ELSE

PRINT “Large Files Not Supported”

END IF

See also

BBSYS30

SYS 99


SYS(34)

SYS(34) ---------- Returns the Operating system precision or next channel number

Type

U/BL function

Syntax

SYS(34)

Description

If the environment variable BBEXTENSION is set to include SDOS (for SuperDOS), the SYS(34) function returns the current precision. 1, 3, or 4, for double, triple, or quadruple precision respectively.

If running without the SuperDOS extensions, the SYS(34) function returns the next channel number.

See also

$CHN


SYS(99)

SYS(99) ---------- Determines which operating system is being used

Type

U/BL function

Syntax

SYS(99)

Description

The SYS(99) function determines which operating system is being used. It returns one of the following values:

0 | UNIX |
1 | DEC VMS | Not Used.
2 | Windows |
3 | Novell Netware | Not Used.
4 | Windows NT/2000 |
5 | Windows 95/98 |

See also

SYS 30


SYS(152)

SYS(152) ---------- Return the Julian value for the current date

Type

U/BL function

Syntax

SYS(152)

Description

This function returns the Julian value for the current system date. A Julian date is one which is expressed as a number of days from a given point. In the case of Business BASIC the given point against which all Julian dates are referenced is the start of 1968. The first of January 1968 is Julian date 1, the second of January 1968 is Julian date 2 and so forth.

The operation of the Julian date routines in U/BL are highly controlled by the environment variable BBJULIANFLAGS (and to a lesser extent BBDATEWINDOW). Dependant on the setting of this environment variable, the value returned by SYS(152) will alter in line with the selected Julian date functionality. Refer to the documentation for BBJULIANFLAGS (and BBDATEWINDOW) for an explanation of the optional functionality.

Example

* dim x$[20]

* x$=$date$(sys(152),0,2003)

* print "The current date is ";x$;" Julian value";sys(152)

The current date is 21-May-1998 Julian value 11099

See also

BBDATEWINDOW

BBJULIANFLAGS

SYS


SYS(161)

SYS(161) ---------- Returns a unique number for each installation

Type

U/BL function

Syntax

SYS(161)

Description

In versions of Basic prior to UBB v3.10, the SYS(161) function returns a unique number for each installation. It is a 32 bit value, where the high 16 bits represent the Transoft VAR number, and the low 16 bits represent the end user number. These values are held in the Banner, and are set up by Transoft. They cannot be changed by the user.

In versions of Basic using the licence banner system introduced in UBB v3.10, the SYS(161) function returns the unique licence number which is held in the banner.

Example

* print sys(161)

8061364

* var=shft(sys(161),-16)

* print var

123

* endusr=shft(sys(161),16)

* endusr=shft(endusr,-16)

* print endusr

456


SYS(165)

SYS(165) ---------- Reports the last operating system internal error number

Type

U/BL function

Syntax

SYS(165)

Description

The SYS(165) function reports the last operating system internal error number. It is useful as a debugging aid when operating system commands fail, for example, READ, WRITE.


SYS(166)

SYS(166) ---------- Reports the maximum number of UBL users allowed by the current licence banner

Type

U/BL function

Syntax

SYS(166)

Description

The SYS(166) function reports the maximum number of U/BL users allowed by the current licence banner.

See also

SYS 167


SYS(167)

SYS(167) ---------- Reports the maximum number of U/SQL users allowed by the current licence banner

Type

U/BL function

Syntax

SYS(167)

Description

The SYS(167) function reports the maximum number of U/SQL users allowed by the current licence banner.

See also

SYS 166


SYS(170)

SYS(170) ---------- Returns the value of the last unpend key pressed

Type

U/BL function

Syntax

SYS(170)

Description

The SYS(170) function returns the value of the last unpend key which was pressed:

Unpend key | SYS(170)
1 | 1
2 | 2
3 | 3
4 | 4


SYS(200)

SYS(200) ---------- Returns the physical line number of the last error

Type

U/BL function

Syntax

SYS(200)

Description

The SYS(200) function returns the physical line number of the last error. The $G program information display command also contains this information.

Example

* list

00010 PRINT

  PRINT 1/0

* run

ERROR 16 - Arithmetic At Line 0 (Physical line 2) In scratch

* ; sys(20), sys(200)

 10 2

*

See also

$G


SYS(999)

SYS(999) ---------- Returns the size of the memory being used by Basic in bytes

Type

U/BL function

Syntax

SYS(999)

Description

The SYS(999) function returns the size of the memory being used by Basic in bytes.


SYS(2000)

SYS(2000) ---------- Returns the status of U/BL's year 2000 compliance

Type

U/BL function

Syntax

SYS(2000)

Description

The SYS(2000) function returns a value of one if the version of U/BL running is year 2000 compliant.

All revisions of U/BL greater than U/BL 2.10 are year 2000 compliant, and therefore return a value of one from a call to SYS(2000). Revisions of U/BL prior to revision 2.10 or copies of UBB are not year 2000 compliant and return a value of 0.

Example

* print sys(2000)

 1

See also

SYS


SYS(2028)

SYS(2028) ---------- Returns the current date in MMDDCCYY format

Type

U/BL function

Syntax

SYS(2028)

Description

The SYS(2028) function returns the current system date in the format MMDDCCYY. This function is broadly similar to the SYS(28) function with the exception that the year is returned as 4 digits. Both of these functions will omit any leading 0 on the month value (21st May 1998 would be returned by SYS(2028) as 5211998 not 05211998).

Example

* print sys(2028)

 5211998

See also

SYS


$T

$T --------- Trace debugging command

Type

U/BL command.

Syntax

$T number

Arguments

number

A numeric expression specifying the trace command's level number:

0 - Switches off the trace.

1 - Shows each CHAIN/SWAP and RETURN.

2 - Shows each line number as it is executed.

3 - Also displays the line of code being executed.

Description

The $T command is the Trace debugging command.

See also

$B

$N


$TURN_OFF

$TURN_OFF ----------- Turn off switches

Type

U/BL Command and Statement.

Syntax

$TURN_OFF(keyword)

Arguments

keyword

The switch you wish to turn of. See $TURN_ON for details.

Description

The $TURN_OFF statement is used to turn off one of the switches discussed under $TURN_ON. Many of these switches can be set as U/BL is brought up.


$TURN_ON

$TURN_ON ---------- Turns on a switch

Type

U/BL Command and Statement.

Syntax

$TURN_ON(keyword)

Arguments

keyword

One of the switches discussed below.

Description

The $TURN_ON statement is used to turn on one of the switches described in the table below. The switches stay on unless turned off by the $TURN_OFF statement and are not affected by the CHAIN, SWAP, or NEW statements. Many of these switches can be set as U/BL is brought up.

The $TURN_ON statement can be used as a program statement or as a keyboard command. The switches are as follows:

DOUBLE

The $TURN_ON(DOUBLE) statement emulates double precision arithmetic instead of triple precision, which is the default. There are really only two differences between double and triple precision arithmetic:

1. ASC is sign extended from 4 bytes so that double precision numbers, that is, those occupying 4 bytes, are properly interpreted.

2. Numeric expressions are written to file as double precision numbers; that is, numbers written to file when the DOUBLE switch is on will occupy only 4 bytes, rather than the 6 bytes of triple precision.

On UNIX and Windows platforms, the environment variable BBEXTENSION must include B32 in order to use this statement.

Examples

00020 DIM I$[8]

00030 OPEN FILE[1,15],"TESTFILE"

00040 WRITE FILE[1,0],4

00050 READ FILE[1,0],I$

00060 $H I$

* $turn_on(double)

* run

000001 00 00 00 04....

* $turn_off(double)

* run

000001 00 00 00 04 20 69 73 20.... is

00010 DIM I$[8]

00020 LET I$=CHR$(-1,4)

00030 PRINT ASC(I$[1,4])

* $turn_on(double) * $turn_off(double)

* run * run

-1 4294967295

OVERWRITE

The $TURN_ON(OVERWRITE) statement informs you when lines are being overwritten, when you ENTER a code segment. The switch assists in not inadvertently losing program lines.

It is controlled by the environment variable BBOVERWRITE.

SCREEN_RECORD

The $TURN_ON(SCREEN_RECORD) statement activates the screen recording routine.

The $TURN_OFF(SCREEN_RECORD) statement deactivates the screen recording routine.

Format 4 activates the routine when Basic is executed.

To ensure that the screen is up to date when deactivating screen recording, flush the output buffer with a STMA 8,5 statement immediately before turning off the screen_record routine. On the UNIX and Windows platforms, the environment variable BBEXTENSION must be set to include B32, and the environment variable BBWINDOWS must be in use in order to use this statement.

Example

00020 ON IKEY THEN GOSUB 7500 : INTERRUPT

00030 $SCREEN_INIT E,0,1,1,24,80

00040 $TURN_ON(SCREEN_RECORD)

:

07500 REM INTERRUPT

07505 STMA 8,5 : FLUSH OUTPUT BUFFER

07510 $TURN_OFF(SCREEN_RECORD)

07520 STOP

07530 $SCREEN_PAINT E,0,1,1,24,80

07540 $TURN_ON(SCREEN_RECORD)

07550 RETURN

This subroutine in the program will allow the program to be interrupted and continued so that the screen is restored to the state it was in before the interruption. This is useful for debugging.

SEQUENCE

The $TURN_ON(SEQUENCE) statement issues a warning whenever the line numbers in a file being entered are out of sequence. This is useful for re-ENTERing code after renumbering.

VERBOSE

The $TURN_ON(VERBOSE) statement displays the full pathname of a file when a SAVE or REPLACE occurs. This is useful when links are being used.

It is controlled by the environment variable BBVERBOSE.


TAB

TAB ---------- Sets the tab width

Type

U/BL Command.

Syntax

Format 1:

TAB=width

Format 2:

PRINT [expr;]TAB(n)[;expr]

Arguments

width

Numeric expression representing the number of characters between tab stops

Description

The TAB command (format 1) sets the number of spaces between tab stops on a line. Tab stops are significant when a PRINT statement uses a comma as a delimiter, because output is placed at the tab stops. TAB is a keyboard command only. Use the STMA 4,9 statement within a program.

The TAB expression (format 2) is a special function which can only be used within PRINT and PRINT FILE statements. The output of the next expression can be set at a specific column by including an expression in the form TAB(n), where n represents the column number.

For the TAB statement, columns are numbered from zero to one less than the page width. If n is greater than or equal to the page width, the modulus of TAB and the page width is used. TAB expressions should be followed by a semi-colon, as a comma moves the current position from the column specified by the TAB.

Examples

1. The TAB command

* tab 7

* print 1,2,3

1 2 3

* tab 10

* print 1,2,3

1 2 3

2. The TAB expression.

* print "Hello";TAB(40);"world"

Hello world

See also

BBTAB

BBTABWIDTH


TEXTBOX

TEXTBOX ---------- Displays a region of formatted text

Type

Windows Object Command

Syntax

TEXTBOX(N, ROW, COL, HEIGHT, WIDTH, TEXT$, FONT$, MODE,[STAT])

Arguments

N | Identifies the text box. Note that this is not a Windows object handle
ROW | The location of the top of the object
COL | The location of the left hand side of the object
HEIGHT | The height of the object
WIDTH | The width of the object
TEXT$ | The text to be displayed
FONT$ | Specifies the appearance of the displayed text.
MODE | Specifies how the statement operates
STAT | Optional status return.

Description

The TEXTBOX command creates and displays a formatted area of text. The text displayed is specified in the TEXT$ parameter. The FONT$ and MODE parameters specify the format the text is displayed in.

The FONT$ parameter selects the font used, its size and the color of both the background and the text itself. The FONT$ parameter is a formatted string of the form:

"<font> <size>, <rf> <gf> <bf> , <rb> <gb> <bb>"

where:

  • <font>specifies the name of the font used, for example, 'Arial'

  • <size> specifies the vertical size of the font in tenths of a character (so a size of 5 represents characters that are half the height of the characters displayed on U/Gi's basepanel).

  • <rf><gf><bf> are specified as numbers from 0-255 representing the intensity of each of the individual colors.Collectively they specify the RGB value for the foreground color.

  • <rb><gb><bb> are specified as numbers from 0-255, representing the intensity of each of the individual colors. Collectively, they specify the RGB value for the background color.

The MODE parameter is a simple bitmask, which specifies the justification of the text displayed:

Value | Description
1 | Left justification
0 | Right justification
2 | Center justification

It can be combined with the following display flags:

4 | Puts a border around the text box
8 | Adds a blank title bar to the text box
16 | Displays the text in italics
32 | Displays the text in bold
64 | Displayed the text underlined
128 | Displays the text on a single line which is vertically centered on the object
256 | Displays vertical rather than horizontal text
512 | Requests that the font be drawn using the same aspect ratio (character height to width) as the font displayed on U/Gi's basepanel. Without using this switch, the text displayed will not be scaled, making it hard to draw text which is similar to the base panel's.
1024 | The text box is initially invisible; use a SHOWWO statement subsequently to make the text visible.

Despite the fact that a text box is not a true Windows object and that its identifier is not an object handle, some of the object manipulator commands will work against text boxes. These include the DELETEWO and SHOWWO commands which enable text boxes to be hidden or destroyed when they are no longer required and the SETTEXT command which allows the displayed text to be altered after the box has been created and displayed.

Example

The following example program produces 10 text boxes containing the text 'Hello' with an increasing font size:

DIM FONT$[100]

PRINT @(-30);"TEXTBOX with Various Font Sizes"

DELETEWO(-1)

REM Define the Windows objects' flags

LET HSIZE=512

LET VCENTRE=128

REM Draw 10 example text boxes of increasing size

FOR I=1 TO 10

LET FONT$="Arial ",I,",255 255 255,0 0 0"

TEXTBOX(I,I+2,1,1,5,"Hello",FONT$,HSIZE+VCENTRE)

NEXT I

See Also

DELETEWO

Error codes

SETTEXT

SHOWWO


TINPUT

TINPUT ----------- Accepts data from the keyboard with a timeout

Type

U/BL Command and Statement.

Syntax

TINPUT wait_time [USING "",][@-expr]..[prompt,] var [,var]..[;]

Arguments

wait_time | A numeric expression representing the time to wait for input, in tenths of a second. Wait_time is rounded up to the nearest second. Wait_time can be -1, in which case the default time-out period applies (this is normally ten minutes, but if B32 has been started with the /U switch, it is 24 hours).
@-expr | Any @ expressions to position the cursor, control the terminal and/or restrict input.
prompt | A quoted string literal printed as a prompt before terminal input is accepted. If no prompt is specified a question mark is the default.
var | A numeric or DIMensioned string variable to receive the value of the input.

Description

The TINPUT command works in exactly the same way as the INPUT and INPUT USING commands, except that it times out after the specified time has elapsed with no key pressed. Each time a key is pressed the timer is reset. If TINPUT does time out, the variables it references are not changed.

The SYS(22) statement returns the time remaining after a TINPUT coomand in tenths of a second. It will return zero if a time out occurred. Subtracting this figure from the wait_time does not necessarily give the time taken to input because of the wait_time being reset with each keystroke.

Examples

1. This program fragment waits for one minute for entry of a command, and then times out.

DIM COMMAND$[10]

TINPUT 1000,"Enter command...",COMMAND$

IF SYS(22)=0 THEN END

:

2. This subroutine displays a message at the bottom of the screen, waits for ten seconds or until a key is pressed, and then clears the message.

01000 REM Display message and pause

  PRINT @(23,1);MSG$

  TINPUT 100,@(-10,-1),"Press any key to continue...",Y$

  PRINT @(23,1);@(-33); : Clear to end of screen

  RETURN


TINPUT FILE

TINPUT FILE ----------- Accepts data from a device or file with a timeout

Type

U/BL Command and Statement.

Syntax

TINPUT wait_time, FILE(channel),[USING "",]var[,var]...[;]

Arguments

wait_time | A numeric expression representing the time to wait for input, in tenths of a second. wait_time is rounded up to the nearest second. wait_time can be -1, in which case the default time-out period of ten minutes applies.
channel | A numeric expression representing the Basic channel used to OPEN the file.
var | A numeric or dimensioned string variable to receive the value of the input.

Description

The TINPUT FILE statement works in exactly the same way as the INPUT FILE and INPUT FILE USING statements, except that it times out after the specified time has elapsed with no input received. Each time a item is received pressed the timer is reset.

Use this statement to read devices, such as a time clock. It is appropriate to open the device in mode 8. If the TINPUT FILE statement does time out, the variables it references are not changed. The SYS(22) statement returns the time remaining after a TINPUT FILE statement in tenths of a second. It returns zero if a time out occurs.

See also

TINPUT


TOJULIAN

TOJULIAN ---------- Converts a month, day, and year to a Julian date

Type

U/BL Command.

Syntax

TOJULIAN jdate,month,day,year

Arguments

jdate | A numeric variable in which the converted date is stored. This represents the number of days since Jan 0, 1968
month | A numeric expression that specifies the calendar month (1-12)
day | A numeric expression that specifies the calendar day (1-31)
year | A numeric expression that specifies the last two digits of the calendar year (0-99)

Description

TOJULIAN converts a date in month, day, year representation into a Julian date.

A Julian date is one which is expressed as a number of days from a given point. In the case of Business BASIC the given point against which all Julian dates are referenced is the start of 1968. The first of January 1968 is Julian date 1, the second of January 1968 is Julian date 2 and so forth.

The Julian date processing algorithms in U/BL are highly controlled by the environment variable BJULIANFLAGS (and to a lesser extent BBDATEWINDOW). Dependant on the setting of this environment variable, the operation of any Julian date processing will alter in line with the settings of these environment variables. Please refer to the documentation for BBJULIANFLAGS (and BBDATEWINDOW) for an explanation of the optional functionality.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

This program computes the number of days from today to a user specified date.

10 INPUT USING " " ,"ENTER A CALENDAR DATE (MMDDYY) ",CDATE

15 MO=CDATE/10000 :MO=MONTH

30 DA=MOD (CDATE/100,100) :DA=DAY

40 YR=MOD (CDATE,100) :YR=YEAR

50 TOJULIAN JDATE1, MO, DA, YR :COMPUTE JULIAN DATE

60 TOJULIAN JDATE2, SYS(2), SYS(1), SYS (3) -1900 :COMPUTE CURRENT JULIAN

70 NDAYS=ABS (JDATE1 - JDATE2) :COMPUTE # OF DAYS BETWEEN TODAY AND USER DATE

80 PRINT "THE # OF DAYS FROM TODAY TO" ;CDATE ;"IS" ;NDAYS

90 END

See also

BBDATEWINDOW

BBEXTENSION

BJULIANFLAGS

BBSDOSDATE

FROMJULIAN

STMA 11

STMA 12

$DATE$

$VDATE

SYS(152)


TRANSLATE

TRANSLATE ---------- Translates ASCII to EBCDIC, EBCDIC to ASCII, lowercase to uppercase, and uppercase to lowercase

Type

U/BL Statement.

Syntax

TRANSLATE string-variable,n

Arguments

string-variable

A string variable that contains the string to be translated and receives the translation.

Note: You must DIMension string variables before they can be used

n

A numeric constant indicating one of the following available translation types:

0 | Uppercase and lowercase alphabetic ASCII characters are translated to uppercase alphabetic ASCII characters
1 | ASCII characters are translated to EBCDIC
2 | EBCDIC characters are translation to ASCII
3 | Uppercase ASCII characters are translated to lowercase
4 | Characters with eighth bit are translated to space
5 | Characters without eighth bit are translated to space
6 | Eighth bit is cleared
7 | Eighth bit is set
8 | Characters without eighth bit are translated to space, and eighth bit is cleared on those whose set

Description

The TRANSLATE statement examines every byte in the string to be translated, and converts the byte in accordance with the numeric constant that indicates the translation type.

It is equivalent to the STMA 14 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example for STMA 14.


TRBEGIN

Type

SQL Access command

Syntax

TRBEGIN([CONN$][,STAT])

Arguments

CONN$ | The connection identifier. This argument is optional, it is only required in programs that use multiple concurrent connections. If this argument is specified and the connection exists transactions will be enabled for the specified connection. If the connection identifier is specified and that connection does not exist then an error status of 2 is returned. If the connection identifier is not specified then transactions will be enabled for the current connection.
STAT | An optional parameter which receives the return status.

Description

The TRBEGIN statement enables transaction processing for the specified connection or for the single current connection.

Example

@AddProd&#9;REM Subroutine to add a new product to the catalogue

REM

REM Uses service queries ADD_PROD and ADD_PRICING with

REM product details and pricing passed in DETAILS$ and CHARGE$

TRBEGIN (ER)

EXEC "ADD_PROD", DETAILS$, ER

IF ER=0 THEN

EXEC "ADD_PRICING", CHARGE$, ER

IF ER<>0 THEN

ROLLBACK (ER) : Cannot add pricing so don't add product

IF ER<>0 THEN GOSUB @SeriousError

ELSE

COMMIT (ER) : Update database

IF ER=0 THEN RETURN

END IF

END IF

REM Only reach here under error conditions

GOSUB @AddError

RETURN

See also

COMMIT

EXEC

LOGOFF

ROLLBACK.


TRUN$

TRUN$ ---------- Remove trailing white-space characters from a string

Type

U/BL function.

Syntax

short$=trun$(long$ [,1])

Arguments

short$ | A DIMensioned string variable or substring which receives the truncated long_string.
long$ | A DIMensioned string variable or substring to be truncated
1 | A flag which causes the TRUN$ function to truncate trailing spaces as well as nulls, form-feeds and eol characters.

Description

The TRUN$ function copies long$ into short$ up until the first null, form feed or end-of-line character. With the 1 flag, TRUN$ copies long$ only up to the last non-space character.

The TRUN$ function must only be used in LET statements. It is quite acceptable for short$ to be the same variable as long$.

Statements such as PRINT TRUN$(X$) are only allowed under UNIX.

Example

* list

00010 DIM X$[100]

00020 LET X$="Least said, soonest mended ",FILL$[0]

00030 PRINT "The full length of the string is";LEN(X$)

00040 LET X$=TRUN$(X$)

00050 PRINT "The length of the string after TRUN$ is";LEN(X$)

00060 LET X$=TRUN$(X$,1)

00070 PRINT "The length of the string after TRUN$ with 1 is";LEN(X$)

* run

The full length of the string is 100

The length of the string after TRUN$ is 31

The length of the string after TRUN$ with 1 is 25

On UNIX only:

00030 PRINT TRUN$(X$)


TURN_OFF

TURN_OFF ---------- Resets the value of various flags

Type

U/BL Statement.

Syntax

TURN_OFF(argument)

Arguments

argument

An argument specifying which flag to reset (disable).

Description

When this statement is executed, the flag specified by the argument is turned off (reset). You can use the following arguments:

SCREEN_RECORD | Resetting this flag means that output to the terminal is not saved. Note: When SCREEN_RECORD is reset, the multi-tasking HOT KEY does not work.
EXT_UNPEND | Resetting this flag means that, during INPUT, the extended unpend sequences cannot be used. Because of this, the #UKEY variable is not maintained. You can only use the normal unpend characters.

You can set and reset this flag across SWAPs and CHAINs. (See the EXT_UNPEND statement for details about restrictions on this capability.)

DGCOMP | Setting or resetting this flag is the same as executing the DGCOMP ON or DGCOMP OFF statement
#ERRJMP | Setting or resetting this flag is the same as executing the #ERRJMP ON or #ERRJMP OFF statement

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

...

200 TURN_OFF (#ERRJMP) :DON'T DO ON ERR LOGIC IF ERROR

  RREAD FILE (0, RN) ,REC$

  TURN_ON (#ERRJMP)

  IF #ERR THEN GOSUB 9000 :IF THERE WAS AN ERROR, DISPLAY IT

  .


TURN_ON

TURN_ON ---------- Sets the value of various flags to on

Type

U/BL Statement.

Syntax

TURN_ON(argument)

Arguments

argument

An argument specifying which flag should be set, or enabled.

Description

The TURN_ON statement sets the flag specified by the argument. You can use the following arguments:

SCREEN_RECORD

Setting this flag saves output to the terminal

EXT_UNPEND

Setting this flag causes the extended unpend sequences to be used during INPUT. This means that pressing one of the unpend sequences sets the #UKEY variable.

When setting this flag, TURN_ON checks to see if an extended unpend string has been specified (using EXT_UNPEND). If there is no extended unpend table, the flag is not set.

The setting and resetting of this flag works across SWAPs and CHAINs. (See the EXT_UNPEND statement for important restrictions on this capability.)

DGCOMP

Setting or resetting this flag is the same as executing the DGCOMP ON or DGCOMP OFF statement

#ERRJMP

Setting or resetting this flag is the same as executing the #ERRJMP ON or #ERRJMP OFF statement

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

  .

  .

1000 :Routine to output error message and wait for response

:Inputs:

: ERRMSG$ - string containing error message

  TURN_OFF (SCREEN_RECORD) :turn off screen saving

  SCREEN_BOX EC, 0, 18, 5, 24, 60 :draw message box

  PRINT @(20, 7) ;ERRMSG$;

  INPUT USING " " ,@(22, 7) ,"Press 'CR' to continue" ,X$;

  SCREEN_PAINT EC, 0, 1, 1, 24, 80 :repaint screen (remove message box)

  TURN_ON (SCREEN_RECORD) :turn screen saving back on

  RETURN

  .


@UNPACK

@UNPACK ---------- Unpacks a record string

Type

U/BL Statement.

Syntax

@UNPACK first_field,record,list

Arguments

first_field | A numeric expression that specifies the first field to move from the record string.
record | A string variable from which all the fields from the list are moved.
list | A list of string variables or numeric variables into which the information from the record string is moved.

Description

The @UNPACK statement moves the information from the record string into the variables in the list. The location from which each field is moved and the length are specified by the field specs, which are defined by the @SET statements.

The @UNPACK statement moves the number of bytes specified by the field specs even if the field type is different from the field being moved. For example, if the first field's definition is a six-byte alpha field but the first variable in the list is numeric, 6 bytes are moved from the location in the record string to the numeric variable. If fields longer than 4 (6 for triple precision) are moved into numeric variables, unpredictable results can occur.

If a field references a byte in the record string beyond the current length, a run-time error (#ERR=84) occurs. A field cannot be moved from the record string beyond the current length.

If the field to be moved to a string variable exceed the dimension of the variable, a run-time error (#ERR=83) occurs. When information has been successfully moved to a string variable, its current length is set to the number of bytes moved. If bit 3 of the byte flags is set, the field definition is not used. If field 2 had bit 3 set, @UNPACK 1, REC$,X,Y$,Z*2 would use field definition 1 for X, field definition 3 for Y$ and field definition 4 for Z*2.

This statement is similar to the UNPACK statement, however, the UNPACK statement is more flexible and provides field type error cases. In most cases use the UNPACK statement instead of @UNPACK.

Note: The BBEXTENSION environment variable must be set to include SDOS in order to use this statement.


UCM$

UCM$ ----------- Uncompress a compressed string

Type

U/BL function.

Syntax

target$=UCM$(source$)

Arguments

target$ | A DIMensioned string variable or substring which receives the uncompressed string.
source$ | A DIMensioned string variable or substring containing a compressed string.

Description

The UCM$ function takes a compressed string produced by the CRM$ function and unpacks it. The target and source strings can be the same. The target will be half again as long as the source string.

The CRM$ function works only on the following characters: A-Z (uppercase only), 0-9, and the four characters which are defined by the STMA 10 statement (defaults are space, comma, hyphen and period). Any other character is stored as the first of these four characters. The UCM$ function expands the string using the same system in reverse.

Example

* list

00010 DIM X$[30],Y$[20]

00020 LET X$="DO NOT MEET TROUBLES HALF WAY"

00030 LET Y$=CRM$(X$)

00040 LET X$=""

00050 LET X$=UCM$(Y$)

00060 PRINT X$

* run

DO NOT MEET TROUBLES HALF WAY

See also

UNPACK


UNDEF

UNDEF ---------- Displays the line numbers which are referenced by GOTO and GOSUB statements that have not been defined

Type

U/BL command and statement

Syntax

UNDEF

Description

The UNDEF statement displays the line numbers which are referenced by GOTO and GOSUB statements that have not been defined. Use the UNDEF statement when writing or debugging a large program to check for undefined lines.

Example

* list

00010 GOTO 00040

00020 GOSUB 00090

00030 GOTO 00100

00040 GOSUB 00800

00050 GOTO 00010

* _undef

Undefined Line Numbers:

Line No. Referenced at

00090 00020

00100 00030

00800 00040


UNLOCK

UNLOCK ----------- Remove one lock or all locks held by a process

Type

U/BL Command and Statement.

Syntax

UNLOCK [id]

Arguments

id

A numeric expression corresponding to the id used when the lock was applied.

Description

The UNLOCK command without an argument removes all the file locks held by the process. The UNLOCK command with an id parameter removes the specific lock that id refers to.

UNLOCK with an id of 0 is a special case, and removes all the file locks for the process.

Example

See the LOCK statement for an example.

See also

LOCK


UNPACK

UNPACK ----------- Move elements out of a string

Type

U/BL Command and Statement.

Syntax

UNPACK rform$, record$ [,element]...

UNPACK rform_line, record$ [,element]...

Arguments

rform$ | A string expression representing the format of the record$ argument
record$ | A string expression which contains the elements to be copied.
element | A variable which receives part of the contents of the record$ argument. Strings and numeric variables can be mixed, but they must correspond to the string format.
rform_line | The line number of an RFORM statement corresponding to the format of the record$ argument.

Description

The UNPACK command copies the contents or part of the contents of a string into a number of variables. This command is normally used to extract the components of a record read from a file.

See the RFORM statement for an explanation of the rform$ and rform_line arguments.

Example

* list

00010 DIM RECORD$[80],NAME$[20]

00020 RFORM A20N+20FB

00030 REM The above statement says that the first 20 bytes are a string

00040 REM the next six bytes are a signed integer

00045 REM we then skip 20 bytes

00050 REM the next 5 bytes are an unsigned integer

00060 REM the final byte is an unsigned integer

00065 REM we're not concerned with the rest of the record

00070 OPEN FILE[0,10],"DEBTORS"

00080 READ FILE[0,NO_OF_DEBTORS*80],RECORD$

00085 PRINT "Debtors exceeding their credit limits"

00086 PRINT @(-28);"Name Balance Credit Limit Class";@(-2

00090 $DO_WHILE NOT EOF(0)

00095 LET NO_OF_DEBTORS=NO_OF_DEBTORS+1

00100 UNPACK 00020,RECORD$,NAME$,BALANCE,CREDIT_LIMIT,CREDIT_CLASS

00105 LET AVAILABLE_CREDIT=BALANCE+CREDIT_LIMIT

00110 IF AVAILABLE_CREDIT THEN

00120 PRINT NAME$,BALANCE,CREDIT_LIMIT,CREDIT_CLASS

00130 LET TOTAL_OVERDRAWN=TOTAL_OVERDRAWN+ABS(AVAILABLE_CREDIT)

00140 END IF

00150 READ FILE[0,NO_OF_DEBTORS*80],RECORD$

00160 $END_DO

00170 CLOSE FILE[0][

00180 PRINT @(-28);"Total amount over credit limits";TOTAL_OVERDRAWN

See also

$ASX

ASC

PACK

RFORM

VAL

VALUE


UPPERCASE

UPPERCASE ---------- Resets the terminal control flag for changing characters automatically to upper case

Type

U/BL Statement.

Syntax

UPPERCASE

Description

The UPPERCASE statement resets the value of the UPPERCASE flag to 0. When the flag is reset to 0, lower case characters are changed automatically to upper case.

The UPPERCASE statement is equivalent to the STMA 7,1 statement.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.


USQL

USQL ---------- Produce Report Writer queries with a single line of U/BL code

Type

U/BL command and statement

Syntax

USQL(query$, set$, qstat)

Arguments

query$ | A string variable or string literal containing the Query command, see below.
set$ | A string variable or string literal containing the query characteristics, including where the report is to be output, any report heading, lines per page, etc.
qstat | A numeric variable which contains the query status returned by the USQL command.

Description

Note: The USQL command is really an underscore command, so if the environment variable BBNOUSCORE is set to N this command will have to be preceded with an underscore, that is, USQL.

The following rules regarding the construction of a Query are identical to those that apply within U/SQL Report Writer. Refer to the U/SQL Universal Structured Query Language Report Writer User Manual.

  • The query$ parameter must contain the Query command using five key words as follows:

SELECT items or report FROM records WHERE criteria GROUP BY items SORT BY items;

  • The query in the query$ parameter must be terminated by a semi-colon ';'

  • Any clause may be omitted apart from the "SELECT items or report " clause which is mandatory. Items may be Fields or Variables. A Field may be specified using the Field Name alone or the Record Name and Field Name as follows,RECORD_NAME.FIELD_NAME. The items in the "SELECT items" clause may be expressions but must be enclosed in parentheses as follows:

SELECT STK_TITLE (STK_PRICE*STK_QTYOH) FROM STOCK;

SELECT * FROM CUSTOMER;

is permitted. This will select all fields in the specified record, in this case the CUSTOMER record, which are defined as Primary in the Data Dictionary

  • The maximum number of items in the SELECT items clause is 200.

  • The maximum number of records in the FROM records clause is 20.

  • The maximum number of items in the SORT BY items clause is 20.

  • The maximum number of items in the GROUP BY items clause is 20.

  • The maximum number of clauses the WHERE clause is 25.

  • The maximum length of query$ must be between 500 and 4 000 bytes.

  • Its size can be defined via the USQLMAKQUERY environment variable, and the default size is 500 bytes.

  • The Output File may be set to TERMINAL, PRINTERx, or any File Name;

  • All alpha values should be null-filled.

The set$ parameter is used to define the Query's characteristics. If set$ is used, it must be null-filled to a total length of 256 bytes. The characteristics are shown below with the default entries:

Output file | : Terminal
Report Header | : Report on first record's description in query$
Lines Per Page | : 24
Page Width | : 80
Maximum Lines | : No Maximum
Maximum Records | : No Maximum
Count Records | : On
Key Number | : Not Set
Sort Procedure | : SQL
File Format | : Normal
Item Delimiter | : ;
Line Delimiter | : <10>
Text Delimiter | : "
Mailmerge file | : Not Set
Disk Name Replacement | : Not Set
Overwrite allowed | : N
Download Output | : N
Strip End Spaces | : N
Maximum Lines in Group | : 0
Case Sensitive | : Y
Messages | : Y
First Page | : N

The layout of the set$ parameter is:

Description | Format | Start | End
Output File | Alpha | 1 | 20
Header | Alpha | 21 | 60
Lines per page | Numeric | 61 | 62
Page width | Numeric | 63 | 64
Maximum lines (0=No maximum) | Numeric | 65 | 66
Maximum records (0=No maximum) | Numeric | 67 | 67
Count records (1=On, 0=Off) | Numeric | 69 | 69
Key number (0=Not set) | Numeric | 70 | 70
Sort procedure (must be 1) | Numeric | 71 | 71
File format (0=Normal, 1=Dif, 2=Binary) | Numeric | 72 | 72
Item delimiter | Alpha | 73 | 82
Line delimiter | Alpha | 83 | 92
Text delimiter | Alpha | 93 | 93
Mailmerge file name | Alpha | 94 | 103
Disk name replacement characters | Alpha | 104 | 113
Overwrite output file? (Y/N/A) | Alpha | 114 | 114
Download output (Y/N/E) Note: Only applicable if running via U/Gi | Alpha | 115 | 115
Strip end spaces (Y/N) | Alpha | 116 | 116
Binary index items | Numeric | 117 | 126
Max lines in group (0=No maximum) | Numeric | 127 | 128
Case Sensitive (Y/N) | Alpha | 129 | 129
Messages (Y/N/D) | Alpha | 130 | 130
First Page (Y/N) | Alpha | 131 | 131
Automatic Page Throw (Y/N) | Alpha | 132 | 132

During execution of the USQL command, two types of error may occur:

Error in Query run-time.

If an error occurs at Query run-time, a message is displayed which gives some information about the error. For example, if an application data file was missing.

Error in Query generation.

If an error occurs during Query generation, the qstat parameter returns a number which indicates that an error occurred. 0 indicates no error during Query generation. The following errors may occur:

qstat | Description
63 | Occurrence Field/Variable Must Be Numeric
166 | Disk Name Replacement is not properly defined
167 | Unable to open file USQLUSER.BB
168 | Unable to open PARAM file
169 | File does not exist in PARAM file
359 | File is not on data dictionary.
360 | Record is not on data dictionary.
361 | Index is not on data dictionary.
362 | Field is not on data dictionary.
365 | Cannot connect record.
368 | Too many packed fields in Query.
369 | Too many Expressions or Variables used.
370 | Too many Set items in Query.
371 | Unable to access BBSQLERM file.
372 | Illegal Syntax.
373 | No Items or Records selected.
374 | Too many Records selected.
375 | Summary Item is invalid.
376 | Unable to read minimum bytes from Data Dictionary
377 | Summary Item is not numeric.
378 | Link field is not defined.
379 | Select item is invalid.
380 | Print clause of select item is invalid.
381 | Too many fields selected.
382 | U/SQL License Date Exceeded.
383 | Too many items in group clause.
385 | Too many items in sort clause.
386 | Where clause is invalid.
387 | Occurrence Field Is Not On Data Dictionary.
388 | Expression is invalid.
400 | Unable to open Data Dictionary.
401 | Unexpected Generation Error
403 | Separate
404 | Illegal FOR clause
407 | Illegal PICTURE clause
481 | Sets may only be used in a Driver File
483 | Invalid set subscript
484 | Unable to allocate memory in query generation
485 | Unable To Open The Mailmerge File
514 | Field Terminator missing in Mailmerge File
515 | Syntax Error in Mailmerge File
584 | Report Name
622 | Data Dictionary incorrect revision
652 | Report does not exist
716 | Too many parameters used
751 | Printer Attributes too long
796 | Binary file index items are invalid.
800 | Variable Value is invalid.
817 | Record Type Value is invalid
828 | BREAK must be used with equivalent records
832 | DISTINCT may not be used with summary function
833 | DISTINCT may only be used on body line
834 | DISTINCT may only be used on group total line
835 | DISTINCT may not be used with equivalent connects


$V

$V ------------ Displays all variables by name and variable number

Type

U/BL command.

Syntax

$V

Description

The $V command displays all variables by name and variable number. Numeric variables also show current value. String variables display current and allocated lengths.

Note: The $V command does not display three and four dimensional numeric arrays correctly.


$VAR

$VAR ------------ Displays all variables by name and variable number

Type

U/BL command.

Syntax

$VAR

Description

The $VAR command displays all variables by name and variable number. Numeric variables also show current value. String variables display current and allocated lengths. This command is an alias for the $V command.

Note: The $VAR command does not display three and four dimensional numeric arrays correctly.


$VDATE

$VDATE --------- Takes a date string, date$ and returns it as an encoded integer

Type

U/BL string function

Syntax

$VDATE error,date,date$,date_edit,date_in

Arguments

error | A numeric variable which is set to zero if the string supplied contains a valid date, or 1 if the date is not valid.
date | A numeric variable which receives a numeric representation of the date.
date$ | A string of up to 20 characters containing a date in the edit form specified (or the default format if none is given).
date_edit | A numeric expression containing a code for the format of date$. This argument is optional. If not supplied, it defaults to the value set by $SET_VALUE(DATE_EDIT,expr).
date_in | A numeric expression containing a code for the internal representation returned in jdate. This argument is optional. If not supplied, it defaults to the value set by $SET_VALUE(DATE_IN,expr).

Description

$VDATE is the reverse of $DATE$. It takes a date string, date$ and returns it as an encoded integer, date setting the error variable to indicate whether the supplied date was legal (a zero is returned in 'error' unless the date was invalid).

The method of encoding the date into a numeric value is specified by the optional date_in parameter. This allows for the following encoding methods:

Method | Encoding
0 | Julian date
1 | [Y]Y]YY*65536 + MM*256 + DD
2 | [Y]Y]YY*10000 + MM*100 + DD
2001 | CC*16777216+YY*65536 + MM*256 + DD
2002 | CC*1000000+ YY*10000 + MM*100 + DD

Method 0 converts the date specified in date$ to a Julian date (for an explanation of Julian date encoding, refer to the separate JULIANDATE documentation). Depending on the edit format in use (see below), the date used to generate the Julian encoding will either be the year as supplied in date$ (200X formats) or will have had the century inferred from the date supplied in date$ (formats 0-8). The century inference is based on the standard method used for Julian date conversions which is controlled by the BBJULIANFLAGS environment variable.

For methods 1 and 2, DD and MM represent the day and month values read from date$ and [[Y]Y]YY represents a 2; 3 or 4 digit year also read directly from date$. This year value will either be an offset from 1900; a windowed date (for an explanation of date windowing see the documentation on BBDATEWINDOW) or an absolute year value including the century.

Which particular representation that is in use is purely a software convention and is entirely up to the application programmer (who need only interpret and use the value in a consistent manner). Unlike all the other representations, encoding methods 1 and 2 do not store a version of the year which has had its century inferred from the supplied information. Formats 1 and 2 hold the year exactly as it was specified in the input string.

Encoding methods 2001 and 2002 store the year information with a century value in the numeric representation. This century will either be the value supplied from the input string (200X formats) or will have had the century inferred from the date specified (formats 0-8). As with the Julian date representation, the century inference is based on the standard method controlled by the BBJULIANFLAGS environment variable.

Should date_in not be specified, $VDATE uses the default DATE_IN setting to determine the encoding method to be used.

The format of the input string is defined by the optional date_edit format specifier, which takes one of the following settings:

Value | Format
0 | MM/DD/YY
1 | DD/MM/YY
2 | YY/MM/DD
3 | DD-Mmm-YY
4 | Mmm DD/YY
5 | DDMMYY
6 | MMDDYY
7 | YYMMDD
8 | YY-MM-DD
2000 | MM/DD/CCYY
2001 | DD/MM/CCYY
2002 | CCYY/MM/DD
2003 | DD-Mmm-CCYY
2004 | Mmm DD/CCYY
2005 | DDMMCCYY
2006 | MMDDCCYY
2007 | CCYYMMDD
2008 | CCYY-MM-DD

If date_edit is not specified, $VDATE defaults to using the system DATE_EDIT setting. It is impossible to set an explicit value for date_in without specifying a value for date_edit. Defaulting date_edit also enforces use of the default value for date_in.

Example

* list

00100 DIM X$[20]

00200 LET X$="4/29/88" \ ERROR=0

00300 $VDATE ERROR,J,X$,2,2

00400 PRINT ERROR,J

00500 LET X$="4/32/88"

00600 $VDATE ERROR,J,X$,2,2

00700 PRINT ERROR,J

* run

0 880429

1 0

See also

BBDATEWINDOW

BBJULIANFLAGS

$DATE$

$GET_VALUE

$SET_VALUE


VAL

VAL ---------- Return the numeric value or a string

Type

U/BL function

Syntax

VAL(string$, decimals)

Arguments

string$ | A string expression containing a string of digits, with a plus or minus sign and decimal point also being allowed.
decimals | A numeric variable which receives the number of digits to the right of the decimal point, or -1 if the conversion was not successful.

Description

The VAL function strips leading and trailing spaces from a string and tries to convert it to a number. The string can be successfully converted if it contains only the digits 0-9, with an optional decimal point and leading sign.

If the string is successfully converted, it is returned as an integer, with the decimal places argument receiving the number of digits after the decimal point. If the string cannot be successfully converted, decimal_places is set to -1 and the return value will be the result of the conversion up to the point of failure.

The VALUE statement is similar. The ASC and $ASX functions and the UNPACK command can be used to convert a binary value from a string to a number. Including the VAL statement's error variable in an expression is very dangerous as Basic will not always evaluate the expression correctly. If the error variable appears on the right hand side of the expression, as in the following example:

DEF FNZ(X)=VAL(X$,ER)*10^MAX(0,X-ER)/10^MAX(0,ER-X)

then Basic will evaluate the expression correctly. However, if the error variable is used before the VAL function:

LET X=ER*7+VAL(S$,ER)

then Basic will evaluate this incorrectly. It will use the value of ER after the VAL rather than its initial value. Incidentally, Data General's Business BASIC also has trouble evaluating statements such as:

IF 1+ER+VAL(S$,ER)<>ER+VAL(S$,ER)+1

if the ER variable is modified by the VAL function.

Example

*list

00010 DIM X$[10]

00020 INPUT "Type a number...",X$

00030 IF X$="" THEN END

00030 LET NUMBER=VAL(X$,DECIMALS)

00040 PRINT "Integer result: ";NUMBER;" Decimal places: ";DECIMALS

00050 GOTO 20

* run

Type a number...1234

Integer result: 1234 Decimal places: 0

Type a number...+12.34

Integer result: 1234 Decimal places: 2

Type a number... -12.34

Integer result: -1234 Decimal places: 2

Type a number...no

Integer result: 0 Decimal places: -1

Type a number...23.5-

Integer result: 235 Decimal places: -1

Type a number...

See also

$ASX

ASC

BBFVAL

PACK

RFORM

UNPACK

VALUE


VALUE

VALUE ---------- Convert a string to a number

Type

U/BL Command and Statement.

Syntax

VALUE var, string$ [err_flag, decimals]

Arguments

var | A numeric variable which receives the numeric value of the string.
string$ | A string expression containing a string of digits, with spaces, a plus or minus sign and decimal point also being allowed.
err_flag | A numeric variable which receives a positive value if the string is terminated by a space or a comma, or a negative value if the string is terminated by any other character. err_flag receives zero if the end of the string is reaches without an error.
decimals | A numeric variable which receives the number of digits to the right of the decimal point.

Description

The VALUE command like the VAL function strips leading and trailing spaces from a string and attempts to convert it to a number. The string can be successfully converted if it contains only the digits 0-9, with an optional decimal point and sign. Unlike the VAL function, however the VALUE command allows the sign to trail the number or even to be embedded.

If the first part of the string contains a number, the VALUE command will convert it, and the err_flag parameter will contain a positive value if the delimiting character was a space or comma. The positive value represents the position in the string at which the delimiter was found. A negative value in the err_flag argument indicating that an invalid character other than space or comma was found, normally indicates an invalid number. The err_flag argument contains zero if the whole string is a single valid number.

The decimals argument receives the number of digits to the right of the decimal point if a decimal point is found. If there is no decimal point, the decimals argument receives a large negative number.

Example

* list

00010 DIM X$[10]

00020 INPUT "Type a number...",X$

00030 IF X$="" THEN END

00040 VALUE NUM,X$,ERROR,DEC

00050 PRINT "Integer: ";NUM;" Error code: ";ERROR;" Decimals:";DEC"

00060 GOTO 00020

* run

Type a number...1234

Integer result: 1234 Error code: 0 Decimals: -32764

Type a number...+12.34

Integer result: 1234 Error code: 0 Decimals: 2

Type a number...12.34-

Integer result: -1234 Error code: 0 Decimals: 2

Type a number...no

Integer result: 0 Error code: -1 Decimals: -32768

Type a number...123 456

Integer result: 123 Error code: 4 Decimals: -32765

Type a number...8/4/88

Integer result: 8 Error code: -1 Decimals: -32767

See also

$ASX

ASC

PACK

RFORM

UNPACK

VAL


$W

$W ------------ Displays a message which tells where you are and in which program

Type

U/BL command.

Syntax

$W

Description

The $W command displays a message which tells where you are and in which program. If you are not RUNning a program, the $W command displays the message "Immediate mode".


$WPEDIT

$WPEDIT ---------- Put the user in the WordPerfect Window Editor from within Basic

Type

U/BL Command and Statement.

Syntax

$WPEDIT error,pkt$,str$

Arguments

error | A numeric variable to hold returning error codes.
pkt$ | A string variable containing information for the WordPerfect Window Editor.
str$ | The string in which the text is passed to and from the WordPerfect Window Editor.

Description

The $WPEDIT statement puts the user in the WordPerfect Window Editor from within Basic. This is useful for editing remarks, comments, and notes from within your applications.

It is not necessary to possess WordPerfect to use this statement. To use $WPEDIT, the str$ argument must hold the text and then be FILLed to its maximum length with ASCII 0's. The packet pkt$ argument must be set up as follows:

pkt$(1,4) Set up by Basic; contains $BYTEADDR(str$)

pkt$(5,8) Set up by Basic; contains $BYTEADDR(pkt$)

pkt$(9,12) Set up by Basic; contains 200000, the maximum size for str$.

pkt$(13,16) Reserved for the length of str$ on return

pkt$(17,20) CHR$(left_dimension_of_window,4)

pkt$(21,24) CHR$(right_dimension_of_window,4)

pkt$(25,28) CHR$(top_dimension_of_window,4)

pkt$(29,32) CHR$(bottom_dimension_of_window,4)

pkt$(33,36) CHR$(pos,4), where pos is the is the starting position within string str$ upon entering the window.

pkt$(37,44) Reserved for future use

pkt$(45,48) CHR$(tab_size,4)

pkt$(49,52) Returned by the WordPerfect Window Editor to specify the character which terminates the editing session, which may be one of the following:

247 = F7

241 = F1

27 = Esc

pkt$(53,56) contains $BYTEADDR of a null terminated string of keys which will cause the editor to exit.

Note: The screen coordinates of the WordPerfect Window Editor are one less than the corresponding coordinates in Basic.

The string of keys to exit the editor consists of the ASCII values of normal keys, or, to use function keys, the ASCII value of the second character returned by that key with the high order bit turned on. The character returned by the editor to show which key was used to terminate the edit follows the same convention. Consequently extended characters (those with an ASCII code of greater than 127) cannot be used to terminate the editor.

The editor allows both multi and single-line editing. When a line becomes too long for a window, both types will shift the string within the window; however, the multi-line editor will perform character wrap when a line contains spaces or tabs.

The editor selects multi or single-line editing by checking the vertical dimensions of the window. If the window top and bottom dimensions are equal, the single-line window editor is called; otherwise the multi-line editor is used.

In the string which is passed to the editor, the following characters have special meanings:

ASCII | Meaning
0 | End of string
9 | Tab
10 | Newline
13 | Soft newline. When passed in, this is converted to a space. When passed out, this is where the string wrapped in the window.
1-31 | Displayed as ^A, ^B, etc., except for the characters above
32-126 | Normal ASCII characters
127-159 | Undefined. These characters should not be passed.
160-254 | The Data General International Character Set on 8-bit terminals, or the same as 32-126 on 7-bit terminals.

A single-line window differs from a multi-line one in the following ways:

  • <NEWLINE> exits a single-line window. As a result, <NEWLINE> cannot be entered in a string in this window type.

  • There is no word wrap.

  • Tabs cannot be used.

  • The window does not prompt for deletions.

The user of a program containing the WordPerfect Editor can use a number of features to edit text within a window:

Key | Feature
<Del> | Backspace
<F1> or <ESC> | Cancel
<Del> | Delete char to the left of cursor
<C1> | Delete char to the right of cursor
<Erase EOL> | Delete to EOL
<Erase Page> | Delete to the end of the buffer
<Shift-C1> | Delete word to left of cursor
<Home><Del> | Delete word to left of cursor
<Home><C1> | Delete word to right of cursor
<F7> | Save and exit
<NEWLINE> | Hard return (multi-line window), or exit (single-line).
<Ctrl-Shift-F12> | Typeover/Insert
<Home><Home><UP> | Beginning of document
<Home><Home><LEFT> | Beginning of line
<Home><LEFT> | Beginning of screen
<LEFT> | Left one character
<RIGHT> | Right one character
<Home><Home><DOWN> | End of document
<Home><Home><RIGHT> | End of line
<DOWN> | Down one line
<UP> | Up one line
<F11> | Down one screen
<C2> | Down one screen
<Shift-F11> | Up one screen
<C4> | Up one screen
<Shift-LEFT> | Left one word
<Shift-RIGHT> | Right one word
<F2> | Spelling checker (UNIX only)

Example

Here is a small program to test the WordPerfect Window Editor:

00100 PRINT "WINDOW.BAS - Test WordPerfect Window Editor module"

00200 DIM X$[100],W$[2000],WPKT$[56]

00300 LET W$=FILL$(0) \ WPKT$=FILL$(0)

00350 DELAY 10

00400 REM Set up packet

00470 LET WPKT$[17,20]=CHR$(10,4) : left dimension of window

00480 LET WPKT$[21,24]=CHR$(70,4) : right dimension of window

00490 LET WPKT$[25,28]=CHR$(5,4) : top dimension of window

00500 LET WPKT$[29,32]=CHR$(15,4) : bottom dimension of window

00510 LET WPKT$[33,36]=CHR$(0,4) : start editing in LH corner

00520 LET WPKT$[37,40]=CHR$(0,4) : no input flags

00530 REM wpkt$[41,44]=buffer output flags

00540 LET WPKT$[45,48]=CHR$(5,4) : tab size

00550 REM wpkt$[49,52]=terminating character

01000 $WPEDIT E,WPKT$,W$

01020 IF E THEN PRINT "Error : ";E


WATSAY

WATSAY ----------- Display text in a window at a specified postion

Type

U/BL Command and Statement.

Syntax

WATSAY(wnam$,row,col,str$,attr[,stat])

Arguments

wnam$ | The name of the window in which the text is to be displayed.
row | The line, relative to line 0 of the window, in the window on which the text is to be displayed.
col | The column, relative to column 0 of the window, in the window at which the text is to begin.
str$ | The text to be displayed.
attr | A bit mask holding the text's attributes.
stat | Receives the error code.

Description

The WATSAY statement displays the string of text in the str$ argument in the window wnam$, at position (row,col). The window wnam$ does not have to be visible when the WATSAY command is issued. When the window is shown, the text is displayed. The text's display attribute can be set with the attr argument to select reverse, underscore, and so on. Tthe attr argument is a bit mask made up from:

reverse 1

underscore 2

blinking 4

dim 8

Example

:

00050 WATSAY(WNAM$,3,2,STR$,1,STAT)

00060 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code puts the text held in the str$ parameter into the window, specified in the parameter wnam$ beginning at line 3 column 2 of the window. The row and column positions are relative to row 0 and column 0 of the window respectively. The text is displayed in reverse video when the window is displayed.


WBOTTOM

WBOTTOM --------- P lace the named window at the bottom of the current stack of windows being displayed

Type

U/BL command and statement.

Syntax

WBOTTOM(wnam$[,stat])

Arguments

wnam$ | The name of the window which is to be moved to the bottom of the stack of windows currently on display.
stat | Receives the error code.

Description

The WBOTTOM statement places the named window at the bottom of the current stack of windows being displayed.

Example

:

00100 WBOTTOM(WNAM$,STAT)

00110 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WTOP


WCLEAR

WCLEAR ----------- Clear the designated window

Type

U/BL command and statement.

Syntax

WCLEAR(wnam$[,stat])

Arguments

wnam$ | The name of the window to be cleared.
stat | Receives the error code.

Description

The WCLEAR statement clears the window specified in the wnam$ parameter.

Example

:

00100 WCLEAR(WNAM$,STAT)

00110 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WDELETE

WERASE

WHIDE

WINIT


WCREATE

WCREATE ----------- Create a window

Type

U/BL command and statement.

Syntax

WCREATE(wnam$,wd$[,stat])

Arguments

wnam$ | The name of the window (maximum of 10 characters). This name is used to refer to the window in subsequent window statements, and can be displayed in the bottom right side of the window's frame.
wd$ | Defines the window's dimensions and other characteristics. This string must be DIMensioned to at least 32 bytes and be null filled to its full length when being assigned its values.
stat | Receives the error code.

Description

The WCLEAR statement must be actioned for each window once, to a maximum of 120, subject to memory particularly on Windows platforms. Once a window has been created it can be 'shown' in any subsequent program.

The window's dimensions and other characteristics are specified in a string which would be constructed to contain the following information:

CHR$(NCOL),CHR$(FLAGS)

WD$[0]=CHR$(NATT)[,CHR$(ATT)],FILL$(0)

where:

row

Defines the starting row of the window. The top row is 0. (0-23).

col

Defines the starting column of the window. The left most column is 0. (0-79).

nrow

Defines the number of rows in the window (1-24).

ncol

Defines the number of columns in the window (1-80).

flags

1 = window boxed. This reduces the effective size of the usable area inside the window by 2 rows and 2 columns.

2 = titled. The name of the window appears in the bottom right corner.

4 = shadowed. This shows a shadow effect using 1 column at the right of the window and a row underneath the window. This reduces the effective size of the usable area inside the window.

8 = permanence. This is used to ensure a menu window remains after making a selection. To clear the menu and its window, use the WHIDE statement.

16 = reverse video.

64 = the menu's window is not cleared on an MDELETE. Has no meaning unless permanence is also set, that is, bit 8.

Any combination of these values can be used. For example:

3 = boxed and titled.

5 = boxed and shadowed.

6 = titled and shadowed.

7 = boxed, titled and shadowed.

15= boxed, titled, shadowed and permanent.

16= window will be displayed in reverse video.

0 = none

natt

1 to 16 defines the number of changed attributes to be used within the window.

att

Up to 16 display attribute occurrences

Display Attributes

Programmers can control 4 attributes for screen display (dim,underscore, blink, reverse video) in any combination, giving 16 possible combinations. Within any window it is possible to map each of these attribute combinations onto a specific combination of screen attributes.

The 16 combinations are (- OFF, X ON):

Basic @(value)

ON -38 -40 -52 -57

OFF -39 -41 -53 -58

 | Dim | Blink | Underscore | Reverse
1 | - | - | - | -
2 | - | - | - | X
3 | - | - | X | -
4 | - | - | X | X
5 | - | X | - | -
6 | - | X | - | X
7 | - | X | X | -
8 | - | X | X | X
9 | X | - | - | -
10 | X | - | - | X
11 | X | - | X | -
12 | X | - | X | X
13 | X | X | - | -
14 | X | X | - | X
15 | X | X | X | -
16 | X | X | X | X

This list can be re-arranged for any window so that attributes in that window operate differently.

Suppose you want the window to be in reverse video as the standard blank window, that is, with no attributes set, then the first attribute must be made 2. Then when a reverse video setting is made in the program, you will require, say, a no attribute setting, so the second attribute setting must be set to 1.

00500 DATA 1,"MAIN",2,18,15,60,3,2,2,1 : 2 attributes swapped

  ^

  Two attributes defined

On a colour screen the 4 Basic attributes of dim, underscore, blink and reverse video can be given differing colours.

Example

This sample could be part of a standalone driver program that is initially invoked before CHAINing to the main menu program of the application.

:

00500 DATA 1,"MAIN",2,18,15,60,3,2,2,1 : 2 ATTRIBUTES SWAPPED

00510 DATA 2,"TOP",0,20,12,60,3,0 : 0 ATTRIBUTES

00520 DATA 3,"BOTTOM",12,0,12,60,3,0 : 0 ATTRIBUTES

00600 DATA 0

:

01000 REM INITIALISE WINDOWS

01010 _WINIT(STAT)

01020 GOSUB 08000 : WINDOW ERROR ROUTINE

01030 RETURN

:

01500 REM DEFINE WINDOW CHARACTERISTICS

01510 READ WNO

01520 IF WNO<=0 THEN GOTO 02500

01530 READ WNAM$,ROW,COL,NROW,NCOL,FLAGS,NATTR

01540 FOR I = 1 TO NATTR

01550 READ ATTR[I]

01560 NEXT I

01570 GOSUB 02000 : CREATE A NEW WINDOW

01580 GOTO 01500 : DEFINE WINDOW CHARACTERISTICS

:

02000 REM CREATE A NEW WINDOW

02010 LET WD$=CHR$(ROW),CHR$(COL),CHR$(NROW),CHR$(NCOL),CHR$(FLAGS)

02015 LET WD$[0]=CHR$(NATTR)

02020 FOR I = 1 TO NATTR

02030 LET WD$[0]=CHR$(ATTR[I])

02040 NEXT I

02050 LET WD$[0]=FILL$(0)

02060 _WCREATE(WNAM$,WD$,STAT)

02070 GOSUB 08000 : WINDOW ERROR ROUTINE

02080 RETURN

:

08000 REM WINDOW ERROR ROUTINE

08010 IF STAT=0 THEN RETURN

08020 PRINT "Window Error. WINDOW=";WNAM$;" STAT=";stat

:

See also

WMAKE


WDELETE

WDELETE ----------- Delete the specified window

Type

U/BL command and statement.

Syntax

WDELETE(wnam$[,stat])

Arguments

wnam$ | The name of the window to be deleted.
stat | Receives the error code.

Description

The WDELETE statement is used to physically delete a particular window. The window must not be on display, even if it is fully hidden by another window. To use the same window again, it must be recreated using a WCREATE or a WMAKE statement.

Example

:

00160 WDELETE(WNAM$,STAT)

00170 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code physically deletes the window specified by the wnam$ parameter from the window management system.

See also

WCLEAR

WERASE

WHIDE

WINIT


WERASE

WERASE ----------- Hide all of the windows currently in the window management system

Type

U/BL command and statement.

Syntax

WERASE(stat)

Arguments

stat

Receives the error code.

Description

The WERASE statement has the effect of hiding all of the windows currently in the window management system. It is the equivalent of using the WHIDE statement on each window. If you wish to physically delete a window, use the WDELETE command. If you want to expunge ALL current windows, use the WINIT command, which initializes the window facility.

Example

:

00180 _WERASE(STAT)

00190 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WCLEAR

WDELETE

WHIDE

WINIT


WHIDE

WHIDE ----------- Hide the specified window

Type

U/BL command and statement.

Syntax

WHIDE(wnam$,stat)

Arguments

wnam$ | The name of the window which is to be hidden.
stat | Receives the error code.

Description

The WHIDE statement hides the specified window. If more than one window is on display, processing returns to the previous "top" window in the stack.

If you want to hide all the windows, use the WERASE statement. If you wish to physically delete a window, use the WDELETE statement. If you want to expunge ALL current windows, use the WINIT statement, which initializes the window facility.

Example

:

00180 WHIDE(WNAM$,STAT)

00190 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WCLEAR

WDELETE

WERASE

WINIT

WSHOW


WINFO

WINFO ----------- Returns window information

Type

U/BL command and statement.

Syntax

WINFO(wnam$,x$[,stat])

Arguments

wnam$ | The name of the window.
x$ | A string to receive the window information. It must be DIMensioned to at least 4 bytes.
stat | Receives the error code.

Description

The WINFO statement returns 4 bytes of information in the x$ parameter representing the row, column, number of rows and number of columns for a given window.

Example

:

00270 WINFO(WNAM$,X$,STAT)

00280 GOSUB 08000 : WINDOW ERROR ROUTINE

00290 LET ROW=ASC(X$[1,1]) \ COL=ASC(X$[2,2])

00300 LET NROW=ASC(X$[3,3]) \ NCOL=ASC(X$[4,4])

:

See also

WSTAT


WINIT

WINIT ---------- Initialize the window facility

Type

U/BL command and statement.

Syntax

WINIT(stat)

Arguments

stat

Receives the error code.

Description

The WINIT statement initialises the window facility for up to 120 windows, subject to memory. This is performed only once for all windows, including those required for menus. It can be performed at any time.

It has the effect of clearing the screen, deleting all existing windows and menus and initialising the windows management system.

Example

:

00020 WINIT(STAT)

00030 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WCLEAR

WDELETE

WERASE

WHIDE


WMAKE

WMAKE ----------- Create a window

Type

U/BL command and statement.

Syntax

WMAKE(wnam$,row,col,nrow,ncol,flags,stat)

Arguments

wnam$

The name of the window (maximum of 10 characters). This name is used to refer to the window in subsequent window statements, and can be displayed in the bottom right side of the window's frame.

row

Defines the starting row of the window. The top row is 0. (0-23).

col

Defines the starting column of the window. The left most column is 0. (0-79).

nrow

Defines the number of rows in the window (1-24).

ncol

Defines the number of columns in the window (1-80).

flags

1 = window boxed. This reduces the effective size of the usable area inside the window by 2 rows and 2 columns.

2 = titled. The name of the window appears in the bottom right corner.

4 = shadowed. This shows a shadow effect using 1 column at the right of the window and a row underneath the window. This reduces the effective size of the usable area inside the window.

8 = permanence. This is used to ensure a menu window remains after making a selection. To clear the menu and its window, use the WHIDE statement.

16 = reverse video.

64 = the menu's window is not cleared on an _MDELETE. Has no meaning unless permanence is also set, that is, bit 8.

Any combination of these values can be used. For example:

3 = boxed and titled.

5 = boxed and shadowed.

6 = titled and shadowed.

7 = boxed, titled and shadowed.

15= boxed, titled, shadowed and permanent.

0 = none

stat

Receives the error code.

Description

The WMAKE statement has the same effect as the WCREATE statement, but has a simpler interface, and does not require the setting up of a window descriptor string (such as wd$ in WCREATE). An additional flag (=16) is provided to specify that the window is in reverse video.

U/Gi's behavior with the WMAKE style flags can be modified under program control by using function 16 of the SETGUIOPT statement.

Example

See WCREATE

See also

WCREATE


WMOVE

WMOVE ----------- Move the window

Type

U/BL command and statement.

Syntax

WMOVE(wnam$,row,col[,stat])

Arguments

wnam$ | The name of the window to be moved
row | The new top row position.
col | The new top left column position.
stat | Receives the error code.

Description

The WMOVE statement moves the window to new co-ordinates, defined by the top left hand corner.

Example

:

00090 WMOVE(WNAM$,10,15,STAT)

00100 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code moves the window named by the wnam$ parameter to cursor position (10,15).

See also

WRESIZE


WOFF

WOFF ----------- Turn a window off from within a program

Type

U/BL command and statement.

Syntax

WOFF

Description

The WOFF command turns a window off from within a program. Together with WON this command allows a window to be left on the screen while input/output takes place on some other part of the screen.

Example

:

00500 REM Switch windows off

00510 WOFF

:

: Processing taking place on another part of the screen but the window is still on display

:

00600 REM Switch windows back on. Processing returns to window.

00610 WON

:

See also

WON


WON

WON ----------- Turn a window on from within a program

Type

U/BL command and statement.

Syntax

WON

Description

Turns a window on from within a program. Together with WOFF this command allows a window to be left on the screen while input/output takes place on some other part of the screen.

Example

:

00500 REM Switch windows off.

00510 WOFF

:

: Processing taking place on another part of the screen but the window is still on display

:

00600 REM Switch windows back on. Processing returns to window.

00610 WON

See also

WOFF


WRESIZE

WRESIZE ----------- Resize the window

Type

U/BL command and statement.

Syntax

WRESIZE(wnam$,row,col,nrow,ncol[,stat])

Arguments

wnam$ | The name of the window.
row | The window's new start line.
col | The window's cursor position on the new line.
nrow | Defines the new number of rows.
ncol | Defines the new number of columns.
stat | Receives the error code.

Description

The WRESIZE statement changes the position of the window specified in the wnam$ parameter to the position specified in the (row,col) parameters, and its dimensions to those given by the nrow parameter (the number of rows) and the ncol paramter (the number of columns).

Example

:

00140 _WRESIZE(WNAM$,18,1,4,10,STAT)

00150 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code changes the window wnam$'s position to line 18 column 1, and changes its size to 4 rows by 10 columns.

See also

WMOVE


WRITE

Type

U/BL command and statement.

Syntax

WRITE expression [,expression]...

Arguments

expression

A string, numeric variable or literal to be displayed on the screen

Description

The WRITE command displays the contents of the variables or literals which are its arguments on the screen.

Unlike the PRINT command, numeric expressions are displayed as ASCII characters, and there is no spacing inserted between items. Strings are displayed inclusive of embedded nulls, and there is no limit to the length of a string which can be displayed. No <NEWLINE> character is appended to the end of a WRITE.

Use the WRITE command instead of PRINT when you desire to send binary strings to the terminal, or to print strings longer than 132 characters.

Example

* print "hello there"

hello

* write"hello there"

hello there *

* write 65,66,67,10

ABC

See also

PRINT


WRITE FILE

WRITE FILE --------- Writes binary data to a file

Type

U/BL command and statement.

Syntax

WRITE FILE (channel [,byte]), expr [,expr]....

Arguments

channel | A numeric expression representing the Basic channel number used to OPEN the file.
byte | A numeric expression representing the byte position in the file to begin writing at.
expr | A string or numeric variable or literal to be written to the file.

Description

The WRITE FILE statement writes binary data to a file. Its counterpart is the READ FILE statement. The WRITE FILE statement works for both random and sequential access.

The number of bytes written to the file depends on the size of the variable. With a string variable, the number of bytes written is the DIMensioned length of the string. Unlike the PRINT FILE statement, embedded nulls are written with the rest of the string.

If no other I/O statements (such as POSITION FILE) alter the current position in the file, and the byte argument is not given, each WRITE FILE statement will write its data immediately after the data written by the last. If the byte argument is specified, Basic performs a POSITION FILE before the WRITE FILE. If byte is -1, Basic will append to the file.

If more than one expression is supplied, a separate WRITE is performed for each one. Because an IKEY can interrupt processing between each WRITE, the file might be left in an uncertain state. To avoid this, IKEY can be disabled with the STMA 6,5 statement or the expressions can be combined into one long string.

WRITE FILE [16] is a special case which behaves as a WRITE statement and sends its data to the terminal. It ignores the byte argument.

Example

00120 WRITE FILE[1,RECNO],RECORD$ : WRITE RECORD

See Also

POSITION FILE

READ FILE

WRITE


WSCROLLDOWN

WSCROLLDOWN ---------- Scroll the current window down n lines

Type

U/BL command and statement.

Syntax

WSCROLLDOWN(n[,stat])

Arguments

n | The number of lines to be scrolled down.
stat | Receives the error code

Description

The WSCROLLDOWN statement scrolls the current window down n lines.

Note: If no windows have been defined, the WSCROLLDOWN statement does not have any effect on the whole screen display.

Example

:

00050 WSCROLLDOWN(9,STAT)

00060 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code scrolls the current window down by nine lines.

See also

WSCROLLUP

WSREGION


WSCROLLUP

WSCROLLUP ---------- Scroll the current window up n lines

Type

U/BL command and statement.

Syntax

WSCROLLUP(n[,stat])

Arguments

n | The number of lines to be scrolled up.
stat | Receives the error code

Description

The WSCROLLUP statement scrolls the current window up n lines.

Note: If no windows have been defined, the WSCROLLUP statement does not have any effect on the whole screen display.

Example

:

00050 WSCROLLUP(4,STAT)

00060 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code scrolls the current window up by four lines.

See also

WSCROLLDOWN

WSREGION


WSHOW

WSHOW ----------- Display the specified window

Type

U/BL command and statement.

Syntax

WSHOW(wnam$[,stat])

Arguments

wnam$ | The name of the window which is to be displayed.
stat | Receives the error code.

Description

The WSHOW command displays a window with all subsequent screen processing continuing within the window and relative to its top left hand corner.

Example

:

00210 WSHOW(WNAM$,STAT)

00220 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WHIDE


WSREGION

WSREGION ----------- Defines the scrolling region

Type

U/BL command and statement.

Syntax

WSREGION(top,bottom[,stat])

Arguments

top | The top edge of the scrolling region. The first line of the actual scrolling region is the line after top, that is, top + 1.
bottom | The last line of the scrolling region is the line after bottom, that is, bottom + 1.
stat | Receives the error code.

Description

The WSREGION statement defines the region of the current window that will scroll on a WSCROLLDOWN or WSCROLLUP command. The scrolling region is between the lines (top + 1) and (bottom + 1) inclusive.

The WSREGION statement must be actioned whilst the appropriate window is on top of the windows currently on display. WSREGION still applies even if the window is no longer active.

Example

:

00120 WSREGION(2,6,STAT)

00130 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code sets the scrolling region of the current window to the area between lines 3 and 7 inclusive.

See also

WSCROLLDOWN

WSCROLLUP


WSTAT

WSTAT ---------- Returns the number of usable rows and columns in a window

Type

U/BL command and statement.

Syntax

WSTAT(wnam$,row,col[,stat])

Arguments

wnam$ | A string variable that, if set to "" or if it has no length, results in WSTAT returning statistics for the current window. If set to hold the name of a window, the statistics is for that window.
row | Receives the number of usable rows.
col | Receives the number of usable columns.
stat | Receives the error code.

Description

The WSTAT statement returns the number of usable rows and columns in a window.

Example

:

00070 LET WNAM$=""

00080 WSTAT(WNAM$,NROW,NCOL,STAT)

00090 GOSUB 08000 : WINDOW ERROR ROUTINE

00100 PRINT "Current window has ";NROW;" usable rows & ";NCOL;" usable cols"

00110 LET WNAM$="PRODENQ"

00120 WSTAT(WNAM$,NROW,NCOL,STAT)

00130 GOSUB 08000 : WINDOW ERROR ROUTINE

00140 PRINT WNAM$;" has ";NROW;" usable rows & ";NCOL;" usable cols"

:

See also

WINFO


WTITLE

WTITLE ----------- Put a title on to a given window

Type

U/BL command and statement.

Syntax

WTITLE(wnam$,t$,attr[,stat])

Arguments

wnam$ | The name of the window to be titled.
t$ | A string or string literal holding the title.
attr | A bit mask holding the title's attributes.
stat | Receives the error code.

Description

The WTITLE statement puts a title on to a given window. The title specified in the t$ parameter, is displayed on the top line of the window in the centre.

The title can be printed with an attribute other than the default of reverse video. The attr paramtere is a bit mask made up from:

reverse 1

underscore 2

blinking 4

dim 8

Example

:

00090 _WTITLE(WNAM$,"Product Enquiry",2,STAT)

00100 GOSUB 08000 : WINDOW ERROR ROUTINE

:

The above code displays the text "Product Enquiry" underscored, centred on the top line of window specified in the wnam$ parameter.


WTOP

WTOP --------- P lace the named window at the top of the current stack of windows being displayed

Type

U/BL command and statement.

Syntax

WTOP(wnam$[,stat])

Arguments

wnam$ | The name of the window which is to be moved to the top of the stack of windows currently on display.
stat | Receives the error code.

Description

This statement places the named window at the top of the current stack of windows being displayed.

Example

:

00100 WTOP(WNAM$,STAT)

00110 GOSUB 08000 : WINDOW ERROR ROUTINE

:

See also

WBOTTOM


$XOR

$XOR --------- Performs an exclusive OR on any number of arguments

Type

U/BL Function

Syntax

$XOR(<expression>,<expression>[,<expression>]...)

Arguments

expression

A numeric expression

Description

The $XOR function will performs an exclusive OR on its arguments, performing a logical exclusive OR on the bits of its arguments to get the bits of the result. Use the $XOR function whenever an exclusive OR is required. It is useful for testing flags, encrypting data and turning flags on.

On the UNIX and Windows platforms, the BBEXTENSION environment variable must include B32 in order to use this statement.

Examples

# list

00010 PRINT $XOR(1,2),

00020 PRINT $XOR(1,1,1,1,1,1,1),

00030 PRINT $XOR(3,5,7)

* run

  3 1 1

 | Binary Value | Decimal Value
argument1 | 1 0 1 1 0 0 | 44
argument2 | 1 1 0 1 1 0 | 54
$XOR(argument1,argument2) | 0 1 1 0 1 0 | 26


XOR

XOR ---------- Retrieves the logical bit-wise Exclusive Or of two numeric values

Type

U/BL Function

Syntax

XOR(expression1,expression2)

Arguments

expression1 | Any numeric expression.
expression2 | Any numeric expression.

Description

The XOR function returns the logical bit-wise Exclusive Or of two valid numerical expressions.

You use XOR mainly to flip bits. Generally, one of the two operands is considered to be a mask, which is used to modify the other operand. An good example of the use of this is in encryption. The two operands are operated on in a bit-by-bit manner. A bit in the result is set on only if one of the operands has that bit on, and the other operand has that bit off. Therefore, if both operands have the bit on or both have the bit off, the result has the bit off. When one of the operands is a mask, for every bit position that is one in the mask, the corresponding bit position of the other operand is reversed. Therefore, the mask defines which bits will be flipped, by those positions whose bit is 1 in the mask.

Using the XOR function, if you apply the function twice with the same mask, the result is the original value. This is particularly useful for encryption, because the key (mask) that is used to encrypt is also used to decrypt. For example:

XOR (XOR(A,M),M)

is always be equal to A, for all values of A and M.

Example

This example demonstrates the use of the XOR function.

10 X=245

20 Y=175

30 Z=XOR (X, Y)

35 PRINT "X=" ;" ;", Y=";Y

40 PRINT "XOR (X, Y) =" ;Z

60 END

When executed, this program produces the output shown below:

X=240, Y=175

XOR (X, Y)=90

This is demonstrated by the binary representations shown below:

Bit# 245: 175: | 7 1 1 | 6 1 0 | 5 1 1 | 4 1 0 | 3 0 1 | 2 1 1 | 1 0 1 | 0 1 1
Result: | 0 | 1 | 0 | 1 | 1 | 0 | 1 | 0


YESIKEY

YESIKEY ---------- Resets to 0 the terminal control flag to continue processing if the IKEY interrupts.

Type

U/BL Statement.

Syntax

YESIKEY

Description

The YESIKEY statement SETs the value of the IKEY flag to 0. When the flag is set to 0, an IKEY is processed normally.

Note: The environment variable BBEXTENSION must be set to include SDOS in order to use this statement.

Example

See the example under STMA 5 & 6 & 7.

Alternate Statement

STMA 7,5.


~

~ ------------ Retrieves the logical bit-wise NOT of an expression

Type

U/BL Operator

Syntax

~ expression

Arguments

expression

Any valid expression

Description

The ~ operator retrieves the bit-wise NOT of an expression. This differs from the Boolean logical NOT. It is typically used to set specific bits. The value returned is calculated by a bit-by-bit reversal of the expression. A bit in the return value is ON (set to 1) if the corresponding bit in the expression is OFF (set to 0). A bit in the return value is OFF if the corresponding bit in the expression is ON.

Note: The ~ operator retrieves the 32 bit NOT (48 bit in triple precision) of the expression, rather than just returning TRUE or FALSE. For example, PRINT ~1 displays -2.

Example

The following example demonstrates the use of the ~ operator:

* list

10 INPUT "Enter value for X : ",X

20 PRINT "The bit-wise NOT of ";X;" is ";~X

* run

Enter value of X : 1

The bit-wise NOT of 1 is -2

* run

Enter value of X : -100

The bit-wise NOT of -100 is 99


&

& ------------ Retrieves the bit-wise AND of two expressions

Type

U/BL Operator

Syntax

expression1 & expression 2

Arguments

expression1 | Any valid numeric expression
expression2 | Any valid numeric expression

Description

The & operator retrieves the bit-wise AND of two expressions. The result is equivalent to:

AND(expression1, expression2)

However it differs from the Boolean logical operator AND.

Note: The ~ operator retrieves the 32 bit AND (48 bit in triple precision) of the two expressions, rather than just returning TRUE or FALSE.

If both expression1 and expression2 can only evaluate to 1 or 0, the result is identical to the reult of using the AND operator. If either expression1 and expression2 can evaluate to to something other than 1 or 0, the result may be entirely different to the result of using the AND operator. For example, the statement:

IF X & Y THEN GOTO 100

does not mean that if X is true and Y is true , then branch to 100. It means that if the expression AND(X,Y) is not zero, then branch. To branch when X is true and Y is true, use:

IF X<>0 & Y<>0 THEN GOTO 100 or,

IF X AND Y THEN GOTO 100


?

? ------------ Retrieves the logical bit-wise OR of two expressions

Type

U/BL Operator

Syntax

expression1 ? expression 2

Arguments

expression1 | Any valid expression
expression2 | Any valid expression

Description

The ? operator retrieves the logical bit-wise OR of two expressions. The result is equivalent to:

OR(expression1, expression2)

However it differs from the Boolean logical OR operator.

The ? operator is typically used in conditional statements.

Note: The ~ operator retrieves the 32 bit OR (48 bit in triple precision) of the two expressions, rather than just returning TRUE or FALSE.

If both expression1 and expression2 can only evaluate to 1 or 0, the result is identical to the result of using the OR operator. If either expression1 and expression2 can evaluate to something other than 1 or 0, the result may be entirely different to the result of the OR operator. For example, PRINT 13 ? 0 displays 13.

To retrieve the bit-wise exclusive OR (XOR), see the example below.

Example

The following program retrieves the exclusive OR (XOR) of two numbers:

* list

10 INPUT X

20 INPUT Y

30 Z=(X ? Y) & ~ (X & Y)

40 PRINT "The exclusive OR of ";X;" and";Y, " is";Z

50 END

*run

* 2

* 3

The exclusive OR of 2 and 3 is 1


Embedding ActiveX Controls

Transoft strongly recommended that you work through the following tutorials before starting to use ActiveX controls. Each ActiveX control acts differently. You can get detailed information on the functioning of the particular ActiveX control from the publisher of the control (read this information in depth).

In order to use these tutorials, you will need the following installed on your local PC:

  • Windows 95, Windows 98 or Windows NT 4.0 (Workstation or Server)

  • U/Gi 4.0 or above

  • U/BL 2.20 or above running under Windows 95, Windows 98 or Windows NT 4.0, or UNIX in GUI mode

  • Internet Explorer 3.0 + (3.02+ recommended)

  • The Microsoft Calendar control (for tutorial 1)

  • The Microsoft FlexGrid control (for tutorial 3)

  • Visual BASIC revision 5 (for tutorial 4)

  • The TsTab control (for tutorial 5). This is installed when U/Gi is installed, except for Compact installations.

The following tutorials give concrete examples of how a variety of commonly used ActiveX controls can be used efficiently and quickly, and allows the gentle introduction of some of the more complicated concepts in the area:

  • Tutorial 1. The Microsoft Calendar Control

  • Tutorial 2. Controlling Internet Explorer

  • Tutorial 3. Using the Microsoft FlexGrid

  • Tutorial 4. Writing and using a Visual Basic ActiveX control

  • Tutorial 5. Using the Transoft Tab Control

Note: Before starting the tutorials, you must make sure that you have the relevant ActiveX Control installed on your system.


Tutorial 1. The Microsoft Calendar Control

This tutorial requires the Microsoft Calendar Control, MSCAL.Calendar, which displays and inputs dates.

Creating the ActiveX control

To create the ActiveX control, use the AXCREATE statement, and RUN the following line of Business BASIC:

10 AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

This creates an ActiveX control with a handle of 1, occupying a screen range (5,5)->(15,45). The handle is subsequently used to reference the control. The first string, "Test calendar" specifies the text to be associated with the ActiveX control. This may be the title, or perhaps the content of an edit or combo box. In the case of the Microsoft Calendar Control, this text is not used at all, so it could be left blank.

The next string "MSCAL.Calendar" is a Microsoft specified string, which is used to uniquely specify the type of the control.

The third string is used to specify any license or additional information that may be required by an ActiveX control. The Microsoft Calendar control does not require this information string, so it has been set to a null string ("").

The fourth parameter is a standard Windows object MODE value. The final parameter STAT is used to return error codes.

When the above program is run, the display appears as follows:

Modifying the ActiveX control

Each ActiveX control has a set of values associated with it known as properties. Properties can be written to and read from, however some properties are read-only. They are used to modify the attributes of the control.

The AXSET command is used to set a property on a control. For example, enter the lines below, to set the date in the Microsoft calendar control:

20 AXSET(1,"Day",24)

30 AXSET(1,"Month",6)

40 AXSET(1,"Year",1969)

The AXGET command is used to retrieve the current value of a property. A numeric or string variable must be specified to store the value. Windows will try to convert any type to any type, so if you had passed a string variable rather than a numeric one for the AXGET of "Year", the string "1969" would be returned. For example, enter the program below:

00010 WINIT

00020 PRINT "Change value on the control and press Enter"

00030 AXCREATE(1,5,5,10,40,"Test calendar","MSCAL.Calendar","",0,STAT)

00040 AXSET(1,"Day",24)

00050 AXSET(1,"Month",6)

00060 AXSET(1,"Year",1969)

00070 BUTTON(2,16,22,2,5,"Enter",512,STAT)

00080 DIM B$[20]

00090 SETGUIOPT 5,"<10>"

00100 STMA 6,0

00110 INPUT "",B$

00120 DELETEWO(2)

00130 STMA 7,0

00140 AXGET(1,"Day",DAY)

00150 AXGET(1,"Month",MONTH)

00160 AXGET(1,"Year",YEAR)

00170 DELETEWO(1)

00180 PRINT DAY," OF ",MONTH," ",YEAR

Run the program and change the date on the calendar control. Press the Enter button and the program will print out the date you have specified. For example, if you specified 3 February 1998, the program output will be:

3 OF 2 1998


Tutorial 2. Controlling Internet Explorer

This tutorial requires the Microsoft Internet Explorer control, Shell.Explorer, which is used to control Internet Explorer.

Most of the web browsing functionality of Microsoft Internet Explorer is available in an ActiveX control that is automatically installed when you install the product. Internet Explorer is in fact a very thin wrapper around this ActiveX control. Using this control provides a very convenient way for U/BL programmers to access the Internet or Intranet from within a Business Basic program. Some suggested uses are:

  • Access to support and help pages on the Internet

  • Links to company Intranet pages

  • Display of reports generated in HTML.

ActiveX controls can be run in either design mode or user mode. The default mode used by U/BL is design mode, which allows access to advanced configuration features such as property pages. However, some ActiveX controls, such as the Internet Explorer 4.0 control Shell.Explorer, do not allow the calling of methods in design mode and so we must switch to user mode using the following SETGUIOPT statement:

SETGUIOPT(31,"1")

Design mode, can be restored by entering:

SETGUIOPT(31,"0")

Enter the following program as an example:

5 REM **Clear all existing Windows Objects**

10 DELETEWO(-1)

15 PRINT @(-30);"**Controlling Internet Explorer**"

20 REM **Create ActiveX Control, setting user mode first **

25 SETGUIOPT(31,"1")

30 AXCREATE(1,5,10,15,60,"","Shell.Explorer","",1,STAT)

35 IF STAT<>0 THEN

40 PRINT "Control not installed or not available

45 END

50 END IF

60 AXCALL(1,"GoHome",A,B)

This will create the ActiveX control, and go to the default home page as defined by Internet Explorer using the GoHome method. The real benefits of this control are being able to navigate to a particular web page. For this, the Navigate method must be used. Replace the line 60 above with:

60 AXCALL(1,"Navigate",a,b,"http://www.transoft.com")

The program will access the specified Web site, for example, in this case www.transoft.com, Transoft's web site. All the Internet explorer features, for example, Hyperlinks, ActiveX controls and Java applets work as normal.


Tutorial 3. Using the Microsoft FlexGrid

This tutorial uses the Microsoft FlexGrid Control, MSFlexGridLib.MSFlexgrid which creates and populates a table (grid) of a specified size.

Enter the following program:

00010 LET S=SYS(0)

00020 DIM A$[100]

00030 PRINT @(-30);"* MS FlexGrid ActiveX Demo *"

00040 DELETEWO(-1)

00050 AXCREATE(1,5,5,10,40,"MSG","MSFlexGridLib.MSFlexgrid","",1,STAT)

00060 IF STAT<>0 THEN

00070   PRINT "FlexGrid can't be created. Is it installed?"

00080   END

00090 END IF

00100 LET RLIMIT=20

00110 LET CLIMIT=20

00120 REM **** Do the basic setup on the control

00130 AXSET(1,"Rows",RLIMIT)

00140 AXSET(1,"Cols",CLIMIT)

00150 AXSET(1,"AllowUserResizing",3)

00160 FOR R=0 TO RLIMIT-1

00170   AXSET(1,"Row",R)

00180   FOR C=0 TO CLIMIT-1

00190     AXSET(1,"Col",C)

00200     LET A$=R,",",C

00210     AXSET(1,"Text",A$,STAT)

00220   NEXT C

00230 NEXT R

00240 LET E=SYS(0)

00250 LET R=E-S

00260 PRINT "R/C Test Took ",R," seconds"

Running the above program creates a table with 20 rows and 20 columns.

The size of the grid is specified by the Rows and Cols properties. If the display area is too small to display all the rows and columns in the grid, the control automatically provides a scrolling mechanism to allow you to view all of the cells. The control also supports resizing by the user of the column widths, by dragging the dividing bars with the mouse.

The two FOR loops in the program populate the 400 cells in the table with some dummy data. You can experiment with some of your own values to see how the control operates.

The speed with which the grid is populated can be improved by commenting out the lines where the AXSET command alters the Row or Cols properties during the loop (precede the lines 170 and 190 with the REM statement), and replacing the AXSET command of the Text property with the following line:

00210 AXSET(1,"TextMatrix",A$,STAT,R,C)

This is an example of setting an indexed property. Indexed properties have array-like indices, and in this case the TextMatrix property sets the text value at a particular cell in one operation. This has two advantages:

  • It is faster, as there are only one-third as many calls

  • It is safer, because the user can't change the current cell during the process of setting the value.


Tutorial 4. Writing and using a Visual Basic ActiveX control

ActiveX allows complex GUI front-ends to be written in languages other than U/BL while still maximizing your investment in U/BL code. As well as Visual Basic, Visual C++, Delphi and Visual J++ can all be used for this purpose.

Note: This tutorial requires that Visual Basic 5.0 be installed on your machine. It is possible to use the freely available Visual Basic Control Creation Edition, in this case, refer to the relevant documentation for the procedure, using this tutorial as a basis.

Creating the Project

  1. Start up Visual Basic, and select the ActiveX Control icon. Click Open.

  2. The next step is to name to your project and ActiveX control. In the Project window at the right hand side of the screen, select the first item marked Project1 (Project1), right click and select Project1 Properties… from the menu. The Project Properties dialog box is displayed:

  3. Change the project name to 'VBTest' and click OK.

The ProgID of the control that will be created has now been changed from Project1.UserControl1 to VBTest.UserControl1.

Creating a simple form

The next step is to add some controls to the blank form on the left hand side of the screen, which will act as the user interface for your ActiveX control.

  1. Select the edit box tool [image] from the floating toolbar, and use it to drag out and form two text boxes as in the example below:

  2. Using the same technique select the check box tool [image] and use it to drag out and form a check box.

  3. Select the button tool [image] and use it to drag out and form two buttons.

  4. To add some meaningful text to the buttons, select the first button which contains the text 'Command1'. Using the Property Window at the right hand side of the screen change the Caption property to 'OK':

Using the same technique change the text on the 'Command2' button to 'Cancel'. The display look as follows:

The ActiveX control is now in a state where it can be used from U/BL.

Creating the ActiveX control

Before you convert the form into an ActiveX control, you must link the fields and buttons on the form into properties and events so that they can be can manipulated by U/BL:

  1. The ActiveX Control Interface Wizard is used to do this. If this is not immediately available on the Add-ins menu, use the Add-in Manager on that menu to select it, and make it available.

  2. Start the wizard, and select Next twice to move onto the page titled Create Custom Interface Members.

  3. Using the New button, create three properties, called UserName, UserAddress and IsChecked, and two events, OnOK and OnCancel. If the display appears as below then click Next, otherwise use the Edit button to correct the selections.

You must now specify how these property and event names relate to the buttons and fields on the form:

  1. Select the UserName property in the PublicName list, and use the combo boxes to map it to the "Text" member of the control "Text1":

This links the UserName property to the text shown in the smaller edit box on the form called Text1.

  2. Similarly, link "UserAddress" to the "Text" member of the Text2 control, and IsChecked to the "Value" member of the Check1 control.

  3. To map the OK button, select the OnOK event in the PublicName list and map it to the "Click" member of the "Command1" button. This means that when the Command1 button (marked "OK") is pressed, and OnOK event will be generated. Similarly select the OnCancel event in the PublicName list and map it to the "Click" member of the "Command2" button.

  4. Click the Next button twice and then click Finish to complete the process.

The final step is to actually creating the control. Select "Make VBTest.ocx" from the File menu, and then select OK, as the location of the '.OCX' file is unimportant for now.

Controlling the ActiveX control from U/BL

Invoke U/BL in GUI mode and type in the following program:

00010 REM **** VBAX - Visual Basic ActiveX Control ****

00020 DIM A$[100],NAME$[100],ADDR$[100]

00030 LET NAME$="Mr J.S. Smith"

00040 LET ADDR$="42,Nowhere Street"

00050 LET CH=0

00060 DELETEWO(-1)

00070 SETGUIOPT(5,"<10>")

00080 PRINT @(-30);"***** VBAX - Controlling a Visual Basic ActiveX Control *****"

00090 PRINT "Change the entries and press OK to see the effect, or cancel to  quit"

00100 AXCREATE(1,5,2,15,50,"","VBTest.UserControl1","",0)

00110 AXSET(1,"UserName",NAME$)

00120 AXSET(1,"UserAddress",ADDR$)

00130 AXEVENT(1,"OnOk",5,"")

00140 AXEVENT(1,"OnCancel",7,"")

00150 AXSET(1,"IsChecked",CH)

00160 LET STAT=0

00180 STMA 6,0

00190 INPUT USING "","",A$

00200 STMA 7,0

00210 IF A$="@^1;7;" THEN

00220   DELETEWO(-1)

00230   PRINT @(-30);"Terminating"

00240   END

00250 END IF

00260 AXGET(1,"UserName",NAME$)

00270 AXGET(1,"UserAddress",ADDR$)

00280 AXGET(1,"IsChecked", CH)

00290 PRINT @(23,1);NAME$;" from ";ADDR$;" is ";

00300 IF CH=0 THEN

00310   PRINT "Unchecked";@(-32)

00320 ELSE

00330   PRINT "Checked";@(-32)

00340 END IF

00350 DELAY 50

00360 GOTO 00180

Running the program displays the previously created Visual Basic ActiveX control:

You can change the text in the two text boxes, or select the check box. Clicking the OK button will display the current state of the form in your U/Gi window. For example, if the OK button is pressed while the ActiveX control is as shown above, the following message is displayed:

Mr J.S.Smith from 42, Nowhere Street is Unchecked

Click Cancel to return to the U/BL prompt.


Tutorial 5. Using the Transoft Tab Control

A tab control is provided with U/Gi which is optimized for use with U/BL. This control is unusual because it can contain other ActiveX controls and Windows Objects within itself. This is achieved by hiding and showing these other controls as the selected tab changes. The control is installed into the Windows System directory (system under Windows 95 or 98, system32 under Windows NT) along with a help file tstab.hlp, which describes the control in detail.

Enter the following program:

0010 REM **** TSTab Test Program ****

0020 PRINT @(-30);"TSTab Test Program. Click Exit to Finish"

0030 DELETEWO(-1)

0035 REM ** Create a 3D look windows which is auto-sized **

0040 SETGUIOPT(10,"ON")

0050 SETGUIOPT(5,"<10>")

0060 SETGUIOPT(30,"1")

0070 DIM FON2$[100]

0080 LET FON2$="Times 8,0 0 0,192 192 192"

0090 GOSUB 00290 : ************ Create Controls

0100 AXCREATE(1,5,5,15,60,"","Transoft.TSTabCtrl.1","",0,STAT)

0110 REM **** Set the number of tabs ****

0120 AXSET(1,"Tabs",2)

0130 REM **** Set the labels on the tabs ****

0140 AXSET(1,"Tab(a).Text","Windows Objects",STAT,0)

0150 AXSET(1,"Tab(a).Text","Calendar Control",STAT,1)

0210 DIM B$[20]

0230 STMA 6,0

0240 INPUT "",B$

0250 STMA 7,0

0260 DELETEWO(-1)

0270 WINIT

0280 END

0290 REM ************ Create Controls

0300 REM *** First tab controls ****

0310 BUTTON(100,7,15,1,10,"Exit",512,STAT)

0320 TEXTBOX(101,9,7,1,7,"Title",FON2$,1024,STAT)

00330 REM *** Second tab controls ****

0340 AXCREATE(200,7,6,12,58,"","MSCAL.CAlendar","",5,STAT)

0350 RETURN

Consider the two AXSET statements on lines 00140 and 00150:

0140 AXSET(1,"Tab(a).Text","Windows Objects",STAT,0)

0150 AXSET(1,"Tab(a).Text","Calendar Control",STAT,1)

Some properties are not simple types such as strings or numbers, but can themselves have properties. In order to access these "sub-properties", a period '.' is used to separate the property from the sub property. Additionally, properties that are indexed and have sub-properties (or sub-methods, which is common) need to have some way of indicating the number of indices used to access the property in order to separate them from further parameters following the indices. This is done by adding dummy "parameter lists" after the property to indicate only the number of parameters. Thus the "(a)" following the Tab in the property name indicates only that there is one index used by the tab. The variable names in the parameter list are irrelevant, and only the count of variables is important, so "(a,b)" is the same as "(b,a)", "(a,a)" or even "(z,q)".

In the Transoft Tab Control, each tab is represented by a tab object that is an indexed property of the control. Each tab has a number of sub-properties, such as Text (the label of the tab), ShownControls (controls that are shown when the tab is shown) and HiddenControls (controls that are hidden when the tab is shown). The two AXSET statements set the label of tab 0 to "Windows Objects", and the label of tab 1 to "Calendar control".

The CreateControls subroutine adds the controls to be shown on each tab. For convenience, these are arranged in the ranges: 100-199 for the first tab, and 200-299 for the second tab.

Now we need to make the controls shown and hidden as the tabs change. This is where placing the controls in a range provides a real benefit, as each tab can be told to show or hide its range. Add the following lines before the END statement:

0160 AXSET(1,"Tab(a).ShownControls","100-199",STAT,0)

0170 AXSET(1,"Tab(a).HiddenControls","200-299",STAT,0)

0180 AXSET(1,"Tab(a).ShownControls","200-299",STAT,1)

0190 AXSET(1,"Tab(a).HiddenControls","100-199",STAT,1)

0200 AXSET(1,"CurrentTab",0,STAT)

Try this. The controls should be shown and hidden as you change tabs.

The Tab control has a number of other features described in the help file tstab.hlp, including support for tooltips, disabling tabs, and firing events as the tab changed.


U/Gi ActiveX control tutorials

In order to use these tutorials, you will need the following installed on your local PC:

  • Windows 95, Windows 98 or Windows NT 4.0 (Workstation or Server)

  • Internet Explorer 3.0 + (3.02+ recommended)

  • The Developer installation of U/Gi 4 or above

  • Microsoft Peer Web Server or Microsoft Internet Information Server [optional for Tutorial 2]

The following tutorials give concrete examples of how a variety of commonly used ActiveX controls can be used efficiently and quickly:

  • Tutorial 1. Using the U/Gi ActiveX control within a Web Page

  • Tutorial 2. Scripting the U/Gi ActiveX control

Note: The tutorial '.HTML' files are installed in the UGiWeb\deploy subdirectory under the location where U/Gi 4 is installed. If you have installed U/Gi on a machine which has either Internet Information Server or Peer Web Server installed, and you have chosen to integrate U/Gi for Web deployment, the CODEBASE entries on the example files will have been updated to point to your chosen virtual directory. If you installed U/Gi on a machine not running as a Web server (or you chose not to integrate U/Gi for Web deployment), the CODEBASE entries will contain a dummy entry.


Tutorial 1. Using the U/Gi ActiveX control within a Web Page

This tutorial guides you through using the U/Gi ActiveX control within an Internet browser.

Step 1 – A simple HTML primer

Hypertext Markup Language (HTML) is the most common standard used to write documents on the World Wide Web. An HTML document is a plain-text file which can be edited using any plain-text editor such as Notepad or vi. It consists of text that will appear in the Web browser, along with special codes known as tags. These tags describe to the Web browser how to present the text, and how to provide special features such as hyperlinks, embedded graphics and ActiveX controls. Tags are contained within angled brackets (<>), to distinguish them from normal text, and are case insensitive. For example:

This is in normal text, <B> this is bold </B>, and back to normal again.<p>

Where:

<B> Bold on

</B> Bold off. The forward slash always means "turn off"

<p> The <p> at the end of the line stands for "paragraph"

HTML ignores the formatting of the HTML source file and relies on these tags to specify how to present text.

We will now create a very simple HTML file:

  1. Open up a DOS window (also known as a command prompt)

  2. Go to a temporary directory, and type:

notepad test.html

  3. Into notepad, enter the following:

<HTML>

<HEAD>

<TITLE>Test HTML Page</TITLE>

</HEAD>

<BODY>

<H1>Hello World</H1>

<HR>

This is ordinary text<p>

<HR>

</BODY>

</HTML>

  4. Save the file.

  5. Start Internet Explorer. Select Open from the File menu, click the Browse button and navigate to the temporary directory where the test file was created. Select the file test.html, and click Open, and then OK. Internet Explorer appears as below:

The example HTML file above will now be explained in detail.

  • To identify itself as HTML, the file starts and ends with the tag <HTML>.

  • The next tag, <HEAD>, indicates the start of the header section which contains information that will not be displayed as part of the main page, but contains information such as the author, title, and information for search engines. Looking two lines forward, we see the </HEAD> tag that ends the header section. The header in this case contains only a title, which is typically displayed in the title bar of the Web browser.

  • The part of the document to be displayed is enclosed by a <BODY> … </BODY> section. This is the part of the document that contains displayed information. For this document, the body consists of a heading (text that will be displayed in a larger font) (<H1>…</H1>), a horizontal line indicated by the <HR> tag, some ordinary text, and another line.

This example HTML file in its current state is available in the UgiWeb\Deploy subdirectory as, tut1a.html.

As you can see, HTML is a very simple language for describing text pages. There are many sources for more information on HTML, available at any computer bookshop, or on the Internet itself. Transoft recommends:

Using HTML, by Mark Brown, John Jung and Tom Savola, Que Press (ISBN 0-7897-0758-6).

Step 2 – Embedding the U/Gi ActiveX control

This step looks at the OBJECT tag, which allows the use of ActiveX controls in a HTML page.

  1. Edit the test.html file, and enter the following lines after the first <HR> tag:

<object

classid="clsid:45549D00-BCBA-11D1-AD21-00A0242FCFFD"

width="700" height="400">

</object>

There are three elements within the OBJECT tag:

width | This specifies the width of the ActiveX control
height | This specifies the height of the ActiveX control
classid | This is a special string that specifies the U/Gi ActiveX control rather than any other type of ActiveX control. You must ensure it is correctly entered.

Together the height and width specify how large the ActiveX control will appear on the Web page.

  2. Save the HTML page, and display it in the browser as before. If the old page is still running, press the Refresh button to update it. The screen appears as below:

If not, check the classid line. The rectangle that appears is the U/Gi ActiveX control itself, but nothing will appear in it yet because it has not been told to connect to anything. To gain maximum flexibility, as will be explained in the next tutorial, the U/Gi ActiveX control must be told to connect to a server on start-up.

  3. Edit the test.html file, and add the following lines immediately before the </OBJECT> tag:

<PARAM NAME="HostName" VALUE="localhost">

<PARAM NAME="AutoConnect" VALUE=1>

The U/Gi ActiveX control can attach to any UNIX machine running TCP/IP or to any U/BL server running under Windows. The above code modifies the HTML page so that it instructs the U/Gi control to attach to a suitable machine.

If you do not wish to connect to a version of U/BL running on your Windows PC, substitute the name of the machine that you do wish to connect to for the "localhost" part of the first line. These PARAM tags are used to set properties of the ActiveX control. Most ActiveX controls have a set properties associated with them that dictate how the control operates and U/Gi is no different.

The first PARAM tag that we have added specifies the host name or IP address of the machine that the U/Gi control will connect to. The second PARAM tag above specifies that the U/Gi ActiveX control should connect as soon as the control is created, that is, when the Web page is first displayed. By default, the control does not connect.

  4. Save the modified HTML file, and display this page in Internet Explorer once again. When the page is shown, you will either be presented with the Standard U/BL NT login prompt (if you are attaching to a U/BL server running on a Windows machine) or the UNIX login (if you are attaching to a UNIX machine, you may need to press RETURN a few times before UNIX senses that you want to log in on that TCP/IP line). If this does not happen, ensure the lines entered above are typed correctly, and placed between the <OBJECT> and </OBJECT> tags, (and that the remote U/BL server or UNIX machine is up and running).

  5. Log in, and try running a few programs to satisfy yourself that all is running correctly.

The text of the test HTML page at the current state is available in the UgiWeb\Deploy subdirectory as tut1b.html.

Step 3 – Locating the ActiveX control on the Intranet or Internet

Note: This section requires Microsoft Peer Web Services or Internet Information Server to be installed on the local PC.

So far, we have successfully run U/Gi within a Web page, but we had to install the U/Gi ActiveX control manually. The primary advantage of running U/Gi in a Web browser, is that it is not necessary to install any files manually. The Internet Component Download system can handle this automatically.

In order to do this, however, we must modify the HTML file to indicate where the necessary files can be located.

  1. Edit the HTML file once again, and add the following line within the OBJECT tag, after the classid line and before the width line:

CODEBASE="http://<yourserver>/<yourdirectory>/ugictrli.cab#VERSION=4,0,0,0"

  2. Replace <yourserver> with the host name of your computer, and <yourdirectory> with the name of the directory for Web Server integration entered at install time.

This specifies that the control can be found at the location specified if the version specified (or a later one) is not installed on the local computer. It is usual for ActiveX controls to be stored in '.CAB' files as they provide compression, which can more than halve the download time. Internet Explorer will, if the correct (or later) version is not installed, download the '.CAB' file and automatically install it. This makes it easy to distribute the U/Gi ActiveX control, as this can be done automatically on visiting your Web page. The U/Gi ActiveX control can be updated by changing the VERSION string.

  3. Save the test HTML file. In order to test it we need to unregister the U/Gi control. To do this, open a DOS box and go to the \UGiWeb sub-directory of the U/Gi ActiveX control installation directory, and type:

regsvr32 –u ugictrl.ocx

A message box should appear saying that the control was successfully uninstalled:

  4. Display the HTML file in the browser. The control will be downloaded from the remote site and installed, and will appear as before.

You might like to publish the test HTML file on your Intranet so that you can test automatic download from another client PC.

The text of the test HTML page at the current state is available in the \deploy subdirectory as tut1c.html.

Step 4 - Automatic login and specifying a program to run

Note: The next section requires functionality that is only currently present in extensions to the Telnet protocol present in U/BL for Windows NT and Windows 95/98.

So far, you have been shown how to create a Web page containing instructions on how to connect to a U/BL server. Next you will be shown how to automatically log in and run a Business Basic program, so applications appear immediately when the Web page is loaded.

  1. Start up U/BL Administrator on the U/BL Server, and create a user called UBLInetUser (as in UBL Internet User) with password UGiAX72.

This will be the user account under which Internet users will run U/BL programs. For security reasons, this user account cannot be changed, and you should take steps to ensure that this user account has the minimum access to the system possible.

  2. Edit the test HTML file and add the following between the <OBJECT> and </OBJECT> tags, and after the two existing PARAM tags:

<PARAM NAME=AutoLogin VALUE="Y">

<PARAM NAME=BBPROG VALUE="tdftest">

If you did not configure your HTML file to attach to a Windows machine running U/BL in Step 3, you will also need to modify the hostname of the machine you wish to connect to (change VALUE=... in the PARAM NAME="HostName" tag to reflect the name or IP Address of the machine running U/BL).

The first PARAM value indicates that U/BL should log on using the account specified above. The second specifies the Business Basic program to be run. For security reasons, this cannot contain special characters such as colons, dots or slashes. If these characters were allowed, the possibility could occur that non-permitted programs could be run. The example above runs the tdftest utility program included in ubllib, which is located in the /progs sub-directory of your U/BL installation directory.

  3. Save the files, and display the web page. The program tdftest should appear and run as normal.

The text of the test HTML page at the current state is available in the \deploy subdirectory as tut1d.html.


Tutorial 2. Scripting the U/Gi ActiveX control

This tutorial discusses client side scripting which can be used to increase the usefulness of the U/Gi ActiveX Control. Client-side scripting is the embedding of tags into HTML files that allow small scriptlets, which have the ability to control ActiveX controls, to be run on the client PC when the Web page is displayed.

There are two scripting languages in general use:

  • JavaScript

  • VBScript

The following examples use VBScript, but the same functionality is available in JavaScript.

Step 1 - Allowing the user to choose the Remote Host

First of all, enter the following code into a '.html' file, and display it in the Web browser.

<HTML>

<HEAD>

<TITLE>U/Gi ActiveX Control</TITLE>

</HEAD>

<BODY >

<H1>U/Gi ActiveX Control Edition<HR></H1>

<FORM NAME="LabelControls">

<INPUT TYPE="EDIT" NAME="host" VALUE="localhost">

<INPUT TYPE="BUTTON" NAME="cmdConnect" VALUE="Connect">

</FORM>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub cmdConnect_onClick

 UGi.HostName=LabelControls.host.value

 UGi.Connect

 UGi.TSSetFocus

End Sub

-->

</script>

<object ID="UGi"

   classid="clsid:45549D00-BCBA-11D1-AD21-00A0242FCFFD"

   WIDTH=806 HEIGHT=485

>

</object>

<HR>

(C) 1997-1999 Transoft Limited<p>

</BODY>

</HTML>

The display appears as below:.

A host name can be entered into the edit box, and clicking the Connect button will establish a connection to the named server

  • The HTML code above does not contain the AutoConnect parameter hence, the control does not automatically connect on start-up.

  • The FORM section creates the edit box and button:

<FORM NAME="LabelControls">

<INPUT TYPE="EDIT" NAME="host" VALUE="localhost">

<INPUT TYPE="BUTTON" NAME="cmdConnect" VALUE="Connect">

</FORM>

Each control in the form has a name, and the form itself has a name so each control can be uniquely identified.

  • The SCRIPT tag specifies that the contents are a script written in VBScript as opposed to JavaScript, and contains a subroutine delimited by the Sub / End Sub block:

<SCRIPT LANGUAGE="VBScript">

<!--

Sub cmdConnect_onClick

 UGi.HostName=LabelControls.host.value

 UGi.Connect

 UGi.TSSetFocus

End Sub

-->

</script>

The name of the subroutine is cmdConnect_OnClick, and the Connect button is called cmdConnect. VBScript automatically associates control names with similarly named subroutines, so it knows that when the cmdConnect button is pressed, the cmdConnect_OnClick subroutine is to be called.

  • The U/Gi ActiveX OBJECT tag:

<object ID="UGi"

   classid="clsid:45549D00-BCBA-11D1-AD21-00A0242FCFFD"

   WIDTH=806 HEIGHT=485

>

</object>

The text 'ID="UGi"' identifies the U/Gi ActiveX control by the name U/Gi so it can be uniquely identified on the page. In principle, it is possible to have many ActiveX controls even of the same type on a single HTML page, therefore a unique name is vital.

  • Reviewing the cmdConnect_onClick subroutine (the SCRIPT tag) we can see that all three lines use the ID of the U/Gi ActiveX control (as defined in the OBJECT tag) to identify the instance of the control to which they reflect:

UGi.HostName=LabelControls.host.value

UGi.Connect

UGi.TSSetFocus

The first line retrieves the value of the edit box (called host, on the form LabelControls), and the second line calls a method on the U/Gi control that instructs it to connect to the remote host. The final line returns the input focus to the U/Gi ActiveX control. If this is not done, Internet Explorer will absorb certain keys (RETURN, ESCAPE, arrow keys) before the U/Gi control sees them.

Step 2 – Using SendKeys to navigate Applications

Enter the following code into a '.html' file, and display it in the Web browser.

<HTML>

<HEAD>

<TITLE>U/Gi ActiveX Control</TITLE>

</HEAD>

<BODY >

<H1>U/Gi ActiveX Control Edition<HR></H1>

<FORM NAME="LabelControls">

<INPUT TYPE="BUTTON" NAME="Start" VALUE="Start Recording">

<INPUT TYPE="BUTTON" NAME="End" VALUE="End Recording">

<INPUT TYPE="BUTTON" NAME="Play" VALUE="Play">

</FORM>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub Start_onClick

 UGi.StartRecording()

 UGi.TSSetFocus()

End Sub

Sub End_onClick

 UGi.EndRecording()

 UGi.TSSetFocus()

End Sub

Sub Play_onClick

 UGi.SendKeys(UGi.RecordingString)

 UGi.TSSetFocus()

End Sub

-->

</script>

<object ID="UGi"

   classid="clsid:45549D00-BCBA-11D1-AD21-00A0242FCFFD"

   WIDTH=806 HEIGHT=485

>

<PARAM NAME=AutoConnect VALUE=1>

</object>

<HR>

(C) 1997-1998 Transoft Limited<p>

</BODY>

</HTML>

This implements a very simple keyboard record and playback facility using the U/Gi ActiveX control. Press the Start recording button, and enter some text into U/Gi. Press the End Recording button, and then the Play button, and the text will be played back. This could be used to make it easier for users to navigate around your application on the Web, or to provide queries based on lookup fields in the HTML page.

The functionality used is similar the previous example, but uses three buttons, with a subroutines for each button. It also uses some recording and playback methods, which are detailed in Appendix D.


Appendix A - ActiveX statements error codes

Appendix A - Error codes returned by ActiveX statements

The following error codes are returned by the ActiveX statements:

Error | Code | Description
None | 0 | The command completed successfully
HANDLE_IN_USE | 1 | The handle is already being used
NO_SUCH_HANDLE | 2 | The handle does not refer to a valid Windows Object
OUT_OF_MEMORY | 3 | Not enough memory to complete the operation
COMMUNICATION | 4 | A communication error occurred between U/Gi and U/BL
FILE_NOT_FOUND | 5 | An expected file could not be located
FONT_CREATION | 6 | The specified font could not be created
INVALID_METHOD | 7 | The method specified was not known to the ActiveX control
INVALID_PARAMETER | 8 | The parameter type or value was incorrect
COULD_NOT_OPEN_FILE | 9 | The file was found but could not be opened
FILE_ERROR | 10 | Error reading or writing file
DATE_EARLIER | 11 | FILETRANSFER did not transfer the file because a later version existing as the destination
FILE_EXISTS | 12 | FILETRANSFER did not transfer the file because a file of the same name already exists
UNSUPPORTED | 13 | The operation is not currently supported
NOT_CORRECT_TYPE | 14 | A parameter was not of the correct type, and could not be converted to a valid type
UNKNOWN | 15 | Unknown error invoking method or property operation
OVERFLOW | 16 | The value supplied is too large for the operation
EXCEPTION | 17 | The method call errored internally
WRONG_ARG_COUNT | 18 | Too many or too few parameters
UNKNOWN_EVENT | 19 | The event specified was not known to the ActiveX control
SUBELEMENT_NOT_SUITABLE | 21 | The referenced property of the ActiveX control is not capable of method calls or property setting
REGISTER_FAIL | 22 | The self-registration of the control failed


Appendix B - Windows Object Error Codes

The following error codes are returned by the Windows Object commands:

Error | Code | Description
OK | 0 | No error
OBJEXISTS | 1 | Attempt to create an object with a handle that is already in use
BADHANDLE | 2 | Handle doesn't exist
NOMEMORY | 3 | Out of memory on client machine
COMMSERROR | 4 | Communication error
FILENOTFOUND | 5 | An expected file could not be located
BADFONT | 6 | The specified font could not be created
BADOPERATION | 7 | Inappropriate operation for the Windows object type
INVALIDPARAM | 8 | Invalid parameter
OPENERROR | 9 | The file could not be opened
IOERROR | 10 | Error reading or writing file
TARGETNEWER | 11 | File not updated as dated later than source (not really an error)
TARGETEXISTS | 12 | File already exists (not necessarily an error)


Appendix C - Standard Windows Object Flags

The following flags apply to the MODE value of the Windows objects creation statements, and may be combined by ORing their values onto the relevant statement specific flags:

Name | Value | Description
TABSTOP | 1 | The object can be moved to and from with the <TAB> and <SHIFT>-<TAB> key. The tab order moved through is the same order as the Windows object numeric handles.
GROUP | 2 | The object being created is to be the first in a group of Windows objects. This flag should be set (along with TABSTOP) for the first in a set of radio buttons, and for the first object in the tab order after the last radio button in the group. For full details on this flag, refer to the statement documentation for the RADIOBUTTON statement.
INVISIBLE | 4 | The object is initially invisible.
DISABLED | 8 | The object is initially disabled.
NOBORDER | 16 | The object initially has no border.

Note: These values do NOT apply to text boxes or hotspots which are not Windows objects.

In addition to the creation flags, the behavior of the Windows objects is also influenced by some of the options on the SETGUIOPT statement. Specifically:

Value | Description
5 | Sets the unpend sequence for the Windows objects
7 | Sets the font and point size for the Windows objects
10 | Selects 2 or 3 dimensional Windows objects
13 | Sets the shortcut mode for Buttons
14 | Sets a fractional scaling for the Windows objects' sizes and locations.
24 | Selects in which U/BL window the object will be created.
26 | Selects which button is the default (the one actioned by pressing the RETURN key even if it does not currently have focus).
30 | Selects a level of sizing over the Windows Objects.
31 | Specifies whether an ActiveX control is used in design or user mode.
32 | Suppresses any KILLFOCUS messages when a SETFOCUS statement is used.

Refer to SETGUIOPT statement section for full details.


Appendix D - Properties and methods of the U/Gi ActiveX controls

Appendix D - U/Gi ActiveX Control - Properties and Methods

The following are the supported properties and methods provided by the U/Gi ActiveX control. The control does also provide some other properties and methods but these are not supported. These additional methods are included in the control for internal, Transoft, testing purposes and their operation between revisions of U/Gi is not guaranteed.

At present, the U/Gi control does not possess a working property page. An embryonic property page does exist which details two (HostName and Port) of the controls properties. However, changing their values on this property page is not reflected in the U/Gi control. Transoft intend to provide a working property page for the U/Gi control in a future revision, if you require this functionality please contact Transoft Customer Services.

Properties

Name

Type

Description

*RecordingString

STRING

The U/Gi ActiveX control provides a keyboard recording facility which records the keystrokes made by the user. When recording is enabled each keystroke made is recorded in this property. Once recording is finished the value of this property may be interrogated by the containing application to determine the keystrokes made. A very simple (and non-real world) example of the use of this property can be seen in the second half of Tutorial 2: Scripting the U/Gi ActiveX Control.

AutoConnect

Number

If this property is set to a non-zero value, U/Gi will, on start-up, automatically connect to the host machine specified by the HostName property.

AutoLogin

STRING

If set to a non-null value the U/Gi ActiveX control will try to login to a Windows version of U/BL as the user <UBLInetUser> with a password of <UGiAX72>. For security reasons, the username and password cannot be changed to any other value.

BBPROG

STRING

When the U/Gi control automatically connects and logs on to a Windows version of U/BL, this property allows the specification of the Business BASIC program to be run when U/BL starts. This property emulates the functionality provided by the -r command line switch of the full U/Gi product. For security reasons, the name of the program cannot contain any of the directory path separators or modifiers so the following characters are all excluded:

  • : (colon)

  • \ (back slash)

  • / (forward slash)

  • ! (exclamation point)

  • . (period)

  • ^ (caret).

This is to prevent the possibility of a fraudulent attempt to run a program not normally enabled for the UBLInetUser login, that is, a program outside of that user's BBPROGS or BBSEARCH environment. As this facility relies on the extended communication protocol between U/Gi and Windows versions of U/BL, it is not available when the control is run against a UNIX version of U/BL. In addition, this property is only used when automatically logging on to U/BL.

ConnectionName

STRING

A name to describe the connection.

Port

Number

The TCP/IP port number to which U/Gi will connect. The default value for this property is 23 (this is, the default telnet port that the Windows version of U/BL listens on for incoming connections).

Methods

Name

Description

AboutBox()

Causes the U/Gi control to display its About box

Connect()

Instructs the U/Gi control to connect to the host machine specified by the HostName property.

Disconnect()

Disconnects the U/Gi control from remote host.

EndRecording()

The U/Gi ActiveX control provides a keyboard recording facility which records the keystrokes made by the user. While recording is enabled, each keystroke made is recorded in the RecordingString property. This particular method stops the current recording session. A very simple (and non-real world) example of the use of this method can be seen in the second half of Tutorial 2: Scripting the U/Gi ActiveX Control.

SendKeys(STRING)

Sends the supplied string argument back to the U/Gi control as if it had been typed at the keyboard. The string can be any combination of ASCII keys with the addition that the following mnemonics are supported for representing certain specific keystrokes:

Mnemonic | Represents
{BS} | backpace key
{DEL} | delete key
{ESC} | escape key
{F1} | function key 1
{F2} | function key 2
{F11} | function key 11
{F12} | function key 12
{RET} | return key
{TAB} | tab key

For example, to send function key one followed by the characters DATA and then the return character, call the SendKeys() method with the string {F1}DATA{RET}. Because the '{' character is used to begin a mnemonic representing a particular key, this character cannot on its own be used in as an argument to the SendKeys method. However, the '}' character is fully supported.

When using the keystroke mnemonics with the SendKeys method, if the U/Gi control fails to recognize the mnemonic, the remainder of the string will be ignored, and the string 123{Illegal}4 will only send the key presses 123 from the control.

An example of the use of this method can be seen in the second half of Tutorial 2: Scripting the U/Gi ActiveX Control.

StartRecording()

The U/Gi ActiveX control provides a keyboard recording facility which records the keystrokes made by the user.

This particular method starts recording each keystroke into the RecordingString property. A recording is not additive -- each use of the StartRecording method wipes the existing recording (the contents of the RecordingString property is set to null). However, calling this method while you are still recording will not affect the current record.

A very simple (and non-real world) example of the use of this method can be seen in the second half of Tutorial 2: Scripting the U/Gi ActiveX Control.

TSSetFocus()

Returns focus to the U/Gi ActiveX Control.


Appendix E - U/BL Socket Error Codes

0 | The command completed successfully
1 | The socket is already in use.
2 | The address passed to a SOCKCONN was not in the correct format of hostname:port.
3 | A timeout occurred during the operation. This may be due to a hardware or network failure.
4 | The socket is not valid
5 | The remote end of the socket was closed during the call
6 | Under NT: A network, hardware or protocol failed during the call. This is unlikely to be due to a programming error, and is most usually due to an incorrect network setup.
7 | One of the parameters of the call was invalid
8 | The hostname could not be resolved by the DNS (dynamic name server) system or hosts file. This error could be due to an incorrect network setup.
9 | The port on which a server wishes to run is already in use by another application.
10 | All available sockets are in use
11 | The remote machine was located, but there was no server running on the required port
12 | The hostname was successfully resolved to an IP address, but the machine with that IP address was not found.
1000+ | Under UNIX, a network, hardware or protocol failed during the call. This is unlikely to be due to a programming error, and is most usually due to an incorrect network setup.By subtracting 1000 form this return status you can obtain the value of the UNIX "errno" variable which you can then look up in UNIX system programming documentation.

Note: Do not rely on receiving a particular error code unless you know that you will be running with a consistent environment. This is because the meaning of a particular error code, or the error code returned for any given situation, is likely to change between different TCP/IP stacks on different machines. This is likely to occur even when communicating to a different remote process.


Appendix F - Terminal Characteristics

Some terminal characteristics can be set using STMA 4, and the STMA 6 and 7 statements. Most of these can also be set within PRINT and the INPUT/TINPUT statements with the form:

@(item,value)

Item corresponds to one of the lines in the table below, and is always negative, so that it is not confused with cursor positioning statements. Value is the ASCII value of the character to be assigned to the item, where the item is -1 to -16, or the status flag number where the item is -18.

Item | Meaning
-1 | Line cancel key.
-2 | Character delete echo.
-3 | Character delete key.
-4 | Primary unpend key.
-5 | Secondary unpend key.
-6 | Primary interrupt key.
-7 | Secondary interrupt key.
-8 | Page width. See also BBLINE and STMA 4,8.
-9 | Tab size. See also TAB.
-10 | Maximum number of characters allowed on input. Automatic unpending occurs on the last character if the maximum number of characters set by value is made negative.
-12 | First echoed character when line cancel occurs.
-13 | Second echoed character when line cancel occurs.
-14 | Pad character to be sent after line feeds.
-15 | Number of pad characters to send.
-16 | Primary unpend key, same as -4.
-18 | Set or clear the job status flag corresponding to value. If value is positive, set the indicated flag. If value is negative, clear the indicated flag. See STMA 6 and 7 for further details.


Appendix G - Terminal Control Characters

Within PRINT and the INPUT/TINPUT statements, these @ expressions can be used to perform special terminal functions. Not all expressions work for all terminal types, as implementation is dependent on the capabilities of the terminal. The Terminal Definition File (tdf) can be used to specify the actual codes to be sent to the screen for each terminal type, and additional codes can be specified for terminals which have additional capabilities.

The expression has the form:

@(item)

where item is always negative. Item corresponds to one of the entries in the table below, or an additional code specified in the tdf.

Terminal control characteristics under U/BL (not emulating SuperDOS).

Item | Meaning
-19 | Reset terminal characteristics (items -1 to -15) to their default values for the current terminal type. If the current terminal type has been changed with STMA 2,0 then PRINT @(-19) is necessary to set the new terminal characteristics. See Appendix F.
-20 | Home cursor.
-21 | Move cursor right.
-22 | Move cursor down.
-23 | Move cursor left.
-24 | Move cursor up.
-25 | Sound the bell.
-27 | Cursor to start of current line.
-28 | Cursor to start of next line.
-30 | Clear the screen.
-31 | Clear unprotected fields.
-32 | Clear to the end of line.
-33 | Clear to the end of screen.
-36 | Inserts a line at the current position.
-37 | Deletes the current line.
-38 | Start low intensity.
-39 | Start high intensity.
-40 | Start blinking.
-41 | End blinking.
-42 | Page mode (roll disabled).
-43 | End page mode (roll enabled).
-52 | Start underlining.
-53 | End underlining.
-54 | Start field display enhancement.
-55 | End field display enhancement.
-56 | Restore default display enhancement.
-57 | Start reverse video.
-58 | End reverse video.
-60 | Toggles U/BL's window facility on and off and outputs the sequence defined as @(-97) in the TDF.
-61 | Turns U/BL's window facility off, raw output on and sends the sequence defined for @(-61) in the TDF to the terminal.
-62 | Turns U/BL's window facility on, raw output off and sends the sequence defined for @(-62) in the TDF to the terminal.
-65 | Turns on scrolling in U/BL windows when used with U/Gi in '-g' mode.
-66 | Turns off scrolling in U/BL windows when used with U/Gi in '-g' mode.
-80 | Enters "normal" screen mode. The screen is cleared.
-100,n | Prints the graphical character n (as defined by the box keyword in the TDF), which can take one of the following values: n Graphic --------------------------------- 1 Top left hand 2 Top right hand 3 Bottom left hand 4 Bottom right hand 5 Top horizontal 6 Bottom horizontal 7 Vertical 8 Left intersection 9 Right intersection 10 Top intersection 11 Bottom intersection 12 Cross 13--+ 14 |__________ User selectable 15 | 16--+
-101 | Cursor on
-102 | Cursor off (hide cursor)
-132 | Enters "compressed" screen mode. The screen is cleared.

Terminal control characteristics under U/BL (emulating SuperDOS).

Item | Meaning
-19 | Reset terminal characteristics (items -1 to -15) to their default values for the current terminal type. If the current terminal type has been changed with STMA 2,0 then PRINT @(-19) is necessary to set the new terminal characteristics. See Appendix F.
-20 | Home cursor.
-21 | Move cursor right.
-22 | Move cursor down.
-23 | Move cursor left.
-24 | Move cursor up.
-25 | Sound the bell.
-27 | Cursor to start of current line.
-28 | Cursor to start of next line.
-30 | Clear the screen.
-31 | Clear unprotected fields.
-32 | Clear to the end of line.
-33 | Clear to the end of screen.
-36 | Inserts a line at the current position.
-37 | Deletes the current line.
-38 | Start low intensity.
-39 | Start high intensity.
-40 | Start blinking.
-41 | End blinking.
-42 | Page mode (roll disabled).
-43 | End page mode (roll enabled).
-44 | Start reverse video.
-45 | End reverse video.
-48 | Switches print-pass-through on, also turns U/BL's window facility off, raw output on and sends the sequence defined for @(-48) in the TDF to the terminal.
-49 | Switches print-pass-through off, also turns U/BL's window facility on, raw output off and sends the sequence defined for @(-49) in the TDF to the terminal.
-52 | Start underlining.
-53 | End underlining.
-54 | Enters "normal" screen mode.
-55 | Enters "compressed" screen mode.
-56 | Restore default display enhancement.
-57 | Start reverse video.
-58 | End reverse video.
-60 | If @(-60) is not defined in the TDF, toggles U/BL's window facility on and off and outputs the sequence defined as @(-97) in the TDF. If @(-60) appears in the TDF, this sequence is treated as user defined and it does not alter the state of U/BL's windowing.
-61 | If @(-61) is not defined in the TDF, turns U/BL's window facility off raw output on and sends the sequence defined for @(-98) in the TDF to the terminal. If @(-61) appears in the TDF, this sequence is treated user defined and it does not alter the state of U/BL's windowing.
-62 | If @(-62) is not defined in the TDF, turns U/BL's window facility on, raw output off and sends the sequence defined for @(-99) in the TDF the terminal. If @(-62) appears in the TDF, this sequence is treated user defined and it does not alter the state of U/BL's windowing.
-80 | Enters "normal" screen mode. The screen is cleared.
-97 | Toggles U/BL's window facility on and off and outputs the sequence defined as @(-97) in the TDF.
-98 | If @(-98) or cur_on appear in the TDF this function performs cursor on (show cursor).
-99 | If @(-99) or cur_off appear in the TDF this function performs cursor off (hide cursor).
-100,n | Prints the graphical character n as defined by the box keyword in the TDF.
-100 | User Defined.
-101 | If @(-101) is not defined in the TDF, turns the cursor on, otherwise regarded as a user defined function.
-102 | If @(-102) is not defined in the TDF, turns the cursor off (hide cursor), otherwise regarded as a user defined function.
-132 | Enters "compressed" screen mode. The screen is cleared.


Appendix H - Terminal Definition File Keywords

The following Terminal Definition File (TDF) keywords enhance and improve the action of U/BL on non Data General screens. They also enable proper line-drawing support on non DEC VT type terminals.

Note: Only printable ASCII characters are allowed in the TDF. Do not use any control characters such as TAB.

Not all the TDF keywords apply across UNIX and Windows implementations of the language, some only apply to one particular platform.

Common Keywords

@(-nn)

A sequence of 2 digit hex numbers. and nn is a decimal value. This specifies a user-defined escape sequence that is actioned by a PRINT @(-XX) command. The value for 'nn' can be one of the 'standard' @ sequences; that is, @(-25) sound bell, or a sequence that has no implied meaning, for example, @(-75). By using values for 'nn' that represent the display attribute controls, for example, @(-38) = start dim) it is possible to define escape sequences associated with the four supported display attributes. However, for greater attribute control, it is recommended that the keywords 'atn' (under UNIX) and 'dosattr' (under Windows) are used to define the attributes (see below for the documentation of these TDF keywords.

Under Windows, most of the terminal control sequences are defined by default but under UNIX the sequences must be explicitly defined in the TDF (either by using the @(-nn) format or the relevant UNIX-TDF keyword, see below).

box

Sequences of 2 digit hex numbers which define the characters used for the outlining of windows. They appear in the following order:

Box Position | Graphic
1 | Top left hand
2 | Top right hand
3 | Bottom left hand
4 | Bottom right hand
5 | Top horizontal
6 | Bottom horizontal
7 | Vertical
8 | Left intersection
9 | Right intersection
10 | Top intersection
11 | Bottom intersection
12 | Cross
13 | User selectable
14 | User selectable
15 | User selectable
16 | User selectable

For VT100, 220 and 320 terminals, the correct box characters are displayed automatically, so box should not be included in TDFs used on these screens.

esc

A hexadecimal number. This keyword sets the key which acts as the primary IKEY.

helpexit

A one byte hexadecimal number. This keyword sets the key which acts as the exit key from application Help menus. If helpexit is not present, then the default is the DELETE key. Standard kbf and kbt mapping functionality can be used to map multiple byte key sequences onto the value defined for helpexit.

kbf_

A sequence of 2 digit hex numbers. These entries specify the hexadecimal sequences actually returned from keys. If a key generates a sequence that is not a recognised Data General Business BASIC sequence, then the kbf_... value should be set to this sequence and the key's corresponding kbt_... value should be set to the Data General sequence.

Each time U/BL detects this sequence, it will be remapped to the Data General sequence so that U/BL can process it accordingly.

The description is not recognised by U/BL, and is used for documentation purposes only. The description, that is, the part after the kbf_, can be a maximum of five characters long.

kbt_...

A sequence of 2 digit hex numbers. These entries specify the Data General Business BASIC sequences that U/BL expects to be returned from keys. If a key generates a sequence that is not a recognised Data General Business BASIC sequence, then the kbf_... value should be set to this sequence and the key's corresponding kbt_... value should be set to the Data General sequence.

Certain keyboard values, when received by U/BL, action hot keys and help. The ten hot keys are defined by the decimal values 201 to 210, i.e. c9 to d2 hexadecimal. The help key is defined by the decimal value 200, that is, c8 hexadecimal.

The description is not recognised by U/BL, and is used for documentation purposes only. The description (i.e. the part after the kbt_) can be a maximum of five characters long.

ncol

2 digit hex number[,2 digit hex number]. This entry specifies the number of columns per screen line. Like nrows it is a hexadecimal number, with an optional second hexadecimal number specifying the number of columns in compressed mode.

nrow

2 digit hex number[,2 digit hex number]. This entry specifies the number of rows on the screen. It is a hexadecimal number, with an optional second hexadecimal number specifying the number of rows in compressed mode.

rem

If rem is the first entry in a tdf line then the line will be treated as a comment and its contents ignored.

Comments may also be appended to the end of a valid TDF description by the use of a colon ':'. A colon on its own on a line will cause a fatal error (9131) when U/BL is invoked.

run_err

Sets the attribute, that is, dim, underscore, reverse or link, for run-time error displays.

stma4_4

The decimal code number generated by the key you wish to use as the primary unpend key. This is the equivalent to issuing an STMA 4,4,X in a U/BL program.

stma4_5

The decimal code number generated by the key you wish to use as the secondary unpend key. This is the equivalent to issuing an STMA 4,5,X in a U/BL program.

syn_err

Sets the attribute, that is, dim, underscore, reverse or blink, for syntax error displays.

vdu

Remaps characters which are outside of the normal ASCII range of 1-127. This applies particularly to those character sets which require accented letters, for example.

wpexitkey

One byte hexadecimal number which represents the code generated by the key which is to act as $WPEDIT's cancel and exit key. Standard kbf and kbt mapping functionality can be used to map multiple byte key sequences onto the value defined for wpexitkey.

UNIX Keywords

act_keys

Defines the start value used by external action keys in the user callable "C" routines.

atn

Sets UNIX screen attributes. n is between 1 and 16. The escape sequences defined by this keyword control the sixteen possible combinations of the four character attributes dim, blink, underscore and reverse video.

autowrap

00, 01 or 02.

Specifies if hardware scrolling is not supported (00), or is supported (01 if automatic wrapping occurs when printing past the last column, 02 if it happens when printing on the last column. 02 should be used on Data General D-series and Wyse 50/60 terminals).

avoid

Sequence of 2 digit hex numbers which represent the row/column numbers which cannot be positioned to directly because of problems with TCP/IP.

U/BL will position to the row or column minus 1 and then perform a cursor down/forward to achieve the correct position. This does have the limitation that it is not possible to have two consecutive non-addressable rows or columns.

bol

Sequence of 2 digit hex numbers which will reposition the cursor to the beginning of the current line. If this is not specified, U/BL will default to a value of 0d.

code

ascii or binary.

The method of specifying the way in which the screen co-ordinates appear in cursor positioning sequences:

ascii => as ascii values, for example, 31,30 => 10

binary => as numeric data, for example, 0a => 10

coloffset

A decimal number used where 'mode' is 'binary'; indicates the offset added to the row/col values to generate the cursor positioning sequence. For example, if row 1 represented by 32 in the cursor sequence, then rowoffset should be 31 as 1 + 31 = 32.

compressed

A sequence to enter a 'compressed' mode (usually 132 cols by 24 rows).

cub

A sequence of 2 digit hex numbers. Escape sequence to move cursor backwards (perform an '@(-23)').

cud

A sequence of 2 digit hex numbers. Escape sequence to move cursor down 1 line (perform an '@(-22)').

cuf

A sequence of 2 digit hex numbers. Escape sequence to move cursor forward (perform an '@(-21)').

cup_prefix

cup_infix

cup_suffix

Sequences of 2 digit hex numbers.

Escape sequences that together with the row and column data specify cursor positioning. The general format is:

prefix,<A>,infix,<B>,suffix (<A> & <B> specify the position).

cuu

A sequence of 2 digit hex numbers. Escape sequence to move cursor up 1 line (perform an @(-24)).

cur_off

A sequence of 2 digit hex numbers. The escape sequence to turn the cursor off. Used by STMA 4,101.

cur_on

A sequence of 2 digit hex numbers. The escape sequence to turn the cursor on. Used by STMA 4,101.

end_bl

A sequence of 2 digit hex numbers. Escape sequence to end blinking. More attribute control can be achieved by employing the 'atn' keyword (see above and the on-line help entry for ATTRIBUTES).

end_dim

A sequence of 2 digit hex numbers. Escape sequence to end low intensity (dim). More attribute control can be achieved by employing the 'atn' keyword (see above).

end_rev

A sequence of 2 digit hex numbers. Escape sequence to end reverse video. More attribute control can be achieved by employing the 'atn' keyword (see above).

end_us

A sequence of 2 digit hex numbers. Escape sequence to end underscoring. More attribute control can be achieved by employing the 'atn' keyword (see above).

ed

A sequence of 2 digit hex numbers. Escape sequence to clear display (perform an @(-30)).

el

A sequence of 2 digit hex numbers. Escape sequence to clear to the end of the current line (perform an @(-32)).

ereos

A sequence of 2 digit hex numbers. Escape sequence to erase the contents of screen from the current cursor position to the end of the screen.

gron

A sequence of 2 digit hex numbers. Declares the escape sequence to enter graphics mode. This sequence is automatically used by a @(-100,n) or windowing and boxing.

groff

A sequence of 2 digit hex numbers. Declares the escape sequence to leave graphics mode. This sequence is automatically used by a @(-100,n) or windowing and boxing.

init

Defines a sequence sent to the terminal when U/BL starts. Typical use is to select a line drawing character set.

normal

A sequence to enter 'normal' mode (usually 80 cols by 24rows).

order

row,col or col,row. Specifies which argument to the cursor positioning sequence is first.

roll_off

A sequence of 2 digit hex numbers. Escape sequence to set page mode (used when PRINTing ASCII <19>).

roll_on

A sequence of 2 digit hex numbers. Escape sequence to allow scroll (used when PRINTing ASCII <18>).

rowoffset

A decimal number. Used where 'mode' is 'binary'; indicates the offset added to the row/col values to generate the cursor positioning sequence. For example, if row 1 represented by 32 in the cursor sequence, then rowoffset should be 31 as 1 + 31 = 32.

st_bl

A sequence of 2 digit hex numbers. Escape sequence to start blinking. More attribute control can be achieved by employing the 'atn' keyword (see above).

st_dim

A sequence of 2 digit hex numbers. Escape sequence to start low intensity (dim). More attribute control can be achieved by employing the 'atn' keyword (see above and the on-line help entry for ATTRIBUTES).

st_rev

A sequence of 2 digit hex numbers. Escape sequence to start reverse video. More attribute control can be achieved by employing the 'atn' keyword (see above ).

st_us

A sequence of 2 digit hex numbers. Escape sequence to start underscoring. More attribute control can be achieved by employing the 'atn' keyword (see above).

term

A sequence of 2 digit hex numbers. Declares the escape sequence that issued when U/BL terminates to re-initialise the terminal to the state it was in prior to executing U/BL. This is particularly useful when 'vi' is used after exiting U/BL.

type

One of 'dg'; 'gui'; 'ibm3151'; 'wyse50' or 'vt'. The sequence causes display operation to be tailored to a particular type of terminal:

dg

This keyword allows the correct use of Data General cursor positioning escape sequences. If type is set to dg, or if BBRAWOUT is set to Y, then <30>FP sequences will be sent straight through rather than being converted to the normal cursor positioning sequences defined in the TDF.

gui

This has the same effect as setting the -g switch on the command line. This setting means that the terminal is the U/Gi emulator.

ibm3151

Allows the use of 132 column cursor positioning sequences.

wyse50

U/BL will sleep for one second when changing the number of columns since some users have found that screen corruption can otherwise occur.

vt

Lets U/BL know that the terminal is in VT mode. It will only be needed if scrolling regions are used. This is because scrolling regions usually effect cursor positioning, but this is not the case with VT screens.

wysebox

A sequence of 2 digit hex numbers. Controls screen character attributes when using the _BOX statement on Wyse-50 terminals. If an _BOX statement is used on an area of the screen which is being displayed with one of the screen character attributes (dim, reverse and blink) switched on, then on a Wyse-50 terminal the attribute will be continued into the box.

To prevent this, set the TDF keyword wysebox to the escape sequence which switches all attributes off, that is, 1b,47,30. Note that the attribute(s) will not be switched on again after the right hand edge of the box (this is to emulate the behaviour of SuperDOS Business BASIC).

Windows Keywords

cur_off

00 or 01

A flag indicating that under SuperDOS emulation, the @(-99) terminal control function should turn the cursor off.

cur_on

00 or 01

A flag indicating that under SuperDOS emulation, the @(-98) terminal control function should turn the cursor on.

dosattr

Sets DOS screen attributes. The escape sequences defined by this keyword control the sixteen possible combinations of the four character attributes dim, blink, underscore and reverse video.

mode132

This entry specifies the mode number which is used by the VGA card fitted to the PC to switch the screen into 132 column mode.

There is no standard for this mode on VGA cards, but U/BL defaults to mode number 55 hexadecimal, which is compatible with S3 Incorporated VGA products.

To find the appropriate mode number for your VGA card, consult the card manufacturer's manual. If the VGA card being used requires a mode number other than 55 hexadecimal, use mode132 to specify the number,that is, mode132=n where n is the mode number for that card).


Appendix I - Supported SuperDOS Statements

The following SuperDOS statements are supported in U/BL:

@ACTION | @BLANK | @DESC | @DIM
@DISPSUB | @EDITSUB | @FORMAT | @GET
@GETFLD | @INPUT | @OFFSET | @PACK
@PRINT | @PUTFLD | @REV | @SET
@SETFD | @SETSD | @UNPACK | ~
AUTOLOCK | CHECK | CLEARINP | COMMON
CONTROL | CONVERT | CREATE | DO UNTIL
DO WHILE | EXT_UNPEND | FCB$ | FILELOCK
FORCE | FORCERR | FROMJULIAN | GETACCT
GETCMD | GETCOM1 | GETCOM2 | GETCOM3
GETDELKEY | GETIKEY1 | GETIKEY2 | GETINMAX
GETLINECAN | GETPROG | GETPRTKIND | GETQUEUE
GETRNO | GETSEA | GETSWAPLEV | GETSYSBITS
GETTABSZ | GETTYPE | GETUNPEND1 | GETUNPEND2
GETUNPEND3 | GETUNPEND4 | IASC | ICHR$
INCLUDE | INIT | JOBBYE | JOBIKIEY
JOBINT | LOOP | LOWERCASE | NOCONTROL
NOFILLC | NOTIKEY | QEDIT | RADD
RDEL | READLOCK | REPLY | RESETIKEY
RGSTACK | RINGBUF | RKADD | RKDEL
RKNEXT | RKPREV | RKREAD | RSTACKS
RWNEXT | RWRITE | SCREEN_BOX | SCREEN_INIT
SCREEN_LOAD | SCREEN_PAINT | SCREEN_STORE | SETCOM1
SETCOM2 | SETCOM3 | SETCRAM | SETDELKEY
SETECHOFF | SETECHON | SETFILLC | SETIKEY1
SETIKEY2 | SETINMAX | SETLINECAN | SETPORT
SETPRTKIND | SETQUEUE | SETSEA | SETSWAPLEV
SETSYSBITS | SETTABSZ | SETTYPE | SETUNPEND1
SETUNPEND2 | SETUNPEND3 | SETUNPEND4 | SLOCK
STATCASE | STATCONTROL | STATECHO | STATFILLC
SATIKEY | STRMATCH | SUNLOCK | TOJULIAN
TRANSLATE | TURN_OFF | TURN_ON | UPPERCASE
XCALL | XOR | YESIKEY |


Appendix J - U/BL Line Editing Commands

U/BL supports the following line editing commands (which can be used at the '*' prompt):

CTRL+A | End of line
CTRL+B | Skip word backward
CTRL+E | Insert mode
CTRL+F | Skip word forward
CTRL+H | Backspace
CTRL+K | Delete till end of line
CTRL+X | Right 1 char
CTRL+Y | Left 1 char
CTRL+U | Clear line


Appendix K - Default Key Definitions in U/Gi

Function Keys

U/Gi generates the following default sequences for function keys:

ESC[<key number>~

For example, SHIFT-F1 returns ESC[13~ (The 13 comes from the table below)

Character | ESC | [ | 1 | 3 | ~
Hex value | 1b | 5b | 31 | 33 | 7e
Decimal value | 27 | 91 | 49 | 51 | 126

Table of Function Key values

 | F1 | F2 | F3 | F4 | F5 | F6
NORMAL | 1 | 2 | 3 | 4 | 5 | 6
SHIFT | 13 | 14 | 15 | 16 | 17 | 18
CTRL | 25 | 26 | 27 | 28 | 29 | 30
ALT | 37 | 38 | 39 | 40 | 41 | 42
SH+CTRL | 49 | 50 | 51 | 52 | 53 | 54
SH+ALT | 61 | 62 | 63 | 64 | 65 | 66
CTRL+ALT | 73 | 74 | 75 | 76 | 77 | 78
SH+CTRL+ALT | 85 | 86 | 87 | 88 | 89 | 90

Arrow Keys

The 4 arrow keys return the following sequences:

Up Arrow: ESC[A

Character | ESC | [ | A
Hex value | 1b | 5b | 41
Decimal value | 27 | 91 | 65

Down Arrow: ESC[B

Character | ESC | [ | B
Hex value | 1b | 5b | 42
Decimal value | 27 | 91 | 66

Right Arrow: ESC[C

Character | ESC | [ | C
Hex value | 1b | 5b | 43
Decimal value | 27 | 91 | 66

Left Arrow: ESC[D

Character | ESC | [ | D
Hex value | 1b | 5b | 44
Decimal value | 27 | 91 | 68

Other Keys

Table of other Key values: ESC[<key number>~

Key | Number
Insert | 101
Delete | 102
Home | 103
End | 104
Page Up | 105
Page Down | 106


Appendix L - Sample translation table file

* Skeleton translation table

* --------------------------------------------------------------------

* File name:    tstrans.dat

* Author:       Transoft Limited

* Remarks:      Skeleton character set translation table file.

*

*   Entries to a translation file can be made using the following formats:

*

*       0       - No translation required

*       ddd     - ddd is 1 to 3 decimal digits (0...9)

*       0ooo    - ooo is 1 to 3 octal digits (0...7)

*       0xhh    - hh is 1 to 2 hexadecimal digits (0...9, a...f)

*       0XHH    - HH is 1 to 2 hexadecimal digits (0...9, A...F)

*       'c'     - c is any printable character

*       '\c'    - c is a b f n r t v \ ? ' and "

*       '\ooo'  - ooo is 1 to 3 octal digits (0...7)

*       '\xhh'  - hh is 1 to 2 hexadecimal digits (0...9, a...f, A...F)

*

*   For example, J may be represented as:

*

*       74 0112 0x4a 0X4A 'J' '\112' or '\x4a'

*

*   See entries below for ASCII values x...del as a further example.

* --------------------------------------------------------------------

*     nul     soh     stx     etx     eot     enq     ack     bel

        0       0       0       0       0       0       0       0

*      bs      ht      nl      vt      np      cr      so      si

        0       0       0       0       0       0       0       0

*     dle     dc1     dc2     dc3     dc4     nak     syn     etb

        0       0       0       0       0       0       0       0

*     can      em     sub     esc      fs      gs      rs      us

        0       0       0       0       0       0       0       0

*      sp       !       "       #       $       %       &       '

        0       0       0       0       0       0       0       0

*       (       )       *       +       ,       -       .       /

        0       0       0       0       0       0       0       0

*       0       1       2       3       4       5       6       7

        0       0       0       0       0       0       0       0

*       8       9       :       ;       <       =       >       ?

        0       0       0       0       0       0       0       0

*       @       A       B       C       D       E       F       G

        0       0       0       0       0       0       0       0

*       H       I       J       K       L       M       N       O

        0       0       0       0       0       0       0       0

*       P       Q       R       S       T       U       V       W

        0       0       0       0       0       0       0       0

*       X       Y       Z       [       \       ]       ^       _

        0       0       0       0       0       0       0       0

*       `       a       b       c       d       e       f       g

        0       0       0       0       0       0       0       0

*       h       i       j       k       l       m       n       o

        0       0       0       0       0       0       0       0

*       p       q       r       s       t       u       v       w

        0       0       0       0       0       0       0       0

*       x       y       z       {       |       }       ~     del

      120    0171    0x7a    0X7B     '|'  '\175'  '\x7e'    '\b'

*     128

        0       0       0       0       0       0       0       0

*     136

        0       0       0       0       0       0       0       0

*     144

        0       0       0       0       0       0       0       0

*     152

        0       0       0       0       0       0       0       0

*     160

        0       0       0       0       0       0       0       0

*     168

        0       0       0       0       0       0       0       0

*     176

        0       0       0       0       0       0       0       0

*     184

        0       0       0       0       0       0       0       0

*     192

        0       0       0       0       0       0       0       0

*     200

        0       0       0       0       0       0       0       0

*     208

        0       0       0       0       0       0       0       0

*     216

        0       0       0       0       0       0       0       0

*     224

        0       0       0       0       0       0       0       0

*     232

        0       0       0       0       0       0       0       0

*     240

        0       0       0       0       0       0       0       0

*     248

        0       0       0       0       0       0       0       0


Appendix M - Sample TDF File

rem ********************            - vt220 -           ************************

rem ********************    TERMINAL DEFINITION FILE    ************************

rem

rem      This is a Terminal Definition File (TDF). It is used by the UBB

rem   system to determine the characteristics of this terminal so that it

rem   is compatible with DG DXXX type terminals. For further information

rem   on TDF's, refer to section 16 of the UBB User Manual.

rem

rem      To test a TDF, use 'tdftest' found with the new release of UBB.

rem   To do this type the following in UBB :-

rem

rem   * run "tdftest"

rem ******************** SCREEN ATTRIBUTE REDEFINITION ************************

rem *** General ***

nrow       18                                   : number of rows

ncol       50,84                                : number of columns

compressed 1b,5b,3f,33,68                       : 132 column screen

normal     1b,5b,3f,33,6c                       : 80 column screen

init       1b,5b,31,6d                          : end_dim

term       1b,5b,6d                             : normal

autowrap   01                                   : terminal scrolls on col 81

rem *** Cursor Control ***

cup_prefix 1b,5b                                : cursor prefix

cup_infix  3b                                   : cursor infix

cup_suffix 48                                   : cursor suffix

code       ascii                                : ascii or binary

order      row,col                              : row,col or col,row

rowoffset  0                                    : row offset

coloffset  0                                    : column offset

cuu        1b,5b,41                             : cursor up

cud        1b,5b,42                             : cursor down

cuf        1b,5b,43                             : cursor forward

cub        1b,5b,44                             : cursor back

cur_off    1b,5b,3f,32,35,6c                    : cursor off

cur_on     1b,5b,3f,32,35,68                    : cursor on

rem *** Clearing The Screen ***

ed         1b,5b,3b,48,1b,5b,32,4a,1b,5b,31,6d  : erase display

el         1b,5b,4b                             : erase line

rem *** Text Modes ***

st_bl      1b,5b,35,6d                          : start blinking

end_bl     1b,5b,32,35,6d                       : end blinking

st_us      1b,5b,34,6d                          : start underscore

end_us     1b,5b,32,34,6d                       : end underscore

st_dim     1b,5b,32,32,6d                       : start dim

end_dim    1b,5b,31,6d                          : end dim

st_rev     1b,5b,37,6d                          : start inverse

end_rev    1b,5b,32,37,6d                       : end inverse

rem *** Graphics Codes ***

gron       1b,28,30                             : graphics mode on

groff      1b,28,42                             : graphics mode off

box        6c,6b,6d,6a,71,71,78,74,75           : box characters

rem ************************ KEYBOARD REDEFINITION ****************************

rem      This section maps your terminals function keys to the DG equivalent.

rem   The first  code  (kbf_)  holds the code  that your  keyboard  generates

rem   after pressing a key.  The second (kbt_) is the code that a DG terminal

rem   would  generate  after pressing the same key,  and is the  one that the

rem   program accepts.  The characters after  the underscore are treated as a

rem   comment (maximum of 5 characters).

esc 03                                          : Primary IKEY = <CTRL> C

kbf_nl=0d                                       : DG Primary unpend key

kbt_nl=0a                                       : i.e. Newline set to ENTER key

kbf_cr=0a                                       : DG Secondary unpend key

kbt_cr=0d                                       : i.e. CR set to <CTRL> J

kbf_bs=08                                       : <Backspace>

kbt_bs=7f

kbf_hme=1b,5b,48                                : <Home> = 08 hex

kbt_hme=08

kbf_f1=1b,4f,50                                 : Function keys

kbt_f1=1e,71

kbf_f2=1b,4f,51

kbt_f2=1e,72

kbf_f3=1b,4f,52

kbt_f3=1e,73

kbf_f4=1b,4f,53

kbt_f4=1e,74

kbf_f5=1b,5b,31,37,7e

kbt_f5=1e,75

kbf_f6=1b,5b,31,38,7e

kbt_f6=1e,76

kbf_f7=1b,5b,31,39,7e

kbt_f7=1e,77

kbf_f8=1b,5b,32,30,7e

kbt_f8=1e,78

kbf_f9=1b,5b,32,31,7e

kbt_f9=1e,79

kbf_f10=1b,5b,32,39,7e

kbt_f10=1e,7a

kbf_cup=1b,5b,41                                : cursor keys

kbt_cup=17

kbf_cul=1b,5b,44

kbt_cul=19

kbf_cur=1b,5b,43

kbt_cur=18

kbf_cub=1b,5b,42

kbt_cub=1a


BBIKEYCHECK

Description

The BBIKEYCHECK environment variable affects how often an IKEY check is performed. The default is once every 32 statements.

Increasing the value of this environment variable will make printing via the MS-DOS print spooler much faster.

This environment variable can be changed by a $PUTENV statement.

Example

BBIKEYCHECK=64


BBNXTFREE

Description

If the BBNXTFREE environment variable has been set to the name of a file, then Basic will use the specified SYS(4) value as its internal job slot identifier, that is, the SYS(9) value. This ensures that the same user will always have the same job slot. If the user inadvertently re-starts U/BL without having terminated the previous session correctly, the same job slot will be re-used.

BBNXTFREE allows the BBTTYS file to be overridden, forcing jobs to search for the next free job slot.

The main use of this is for sites where the total number of unique users is greater than the number allowed at one time by the licence.

Example

BBNXTFREE=Y

See also

BBDUPSYS4

BBSYS4INC

BBTTYNO

BBTTYS


External Names used by U/BL

When user written 'C' routines are linked into U/BL the possibility of external name conflict occurs.

U/BL external names 'almost always' begin with a lower case 'u' followed by an upper case letter, or begin with an upper case 'U'.

If link errors occur the user will have to change some of their external names.


Document Feedback

We would appreciate any comments about this User Guide. Please send comments via electronic mail to the following address:

sismail@transoft.com

You can help us by including the following information:

  • Your name

  • Your company's name (optional)

  • Your Internet e-mail address

  • Any additional information that will help us in responding to your comments.


Help on Help

Help is displayed in a three-pane window and can be invoked either from the Help menu on the Analyst Workbench, the Discovery workbench, the Program Viewer or by pressing the F1 function key on your keyboard.

The default Help window consists of three panes:

The following sections describe how to use these panes:

  • Using the toolbar pane

  • Using the navigation pane

  • Using the topic pane

Using the Toolbar Pane

The toolbar pane displays a number of buttons as follows:

Toolbar Button

Description

Hides the navigation pane so that you can maximize the topic pane and view it full width. To restore the navigation pane, click the maximize button again to reduce the size of the topic window, then click Show.

Restores the navigation pane so it can be viewed.

Highlights the topic in the table of contents that is currently open in the topic pane. You can use this to locate your place in the table of contents after you have made jumps between topics in the help system.

Takes you back through a sequence of pages you have already viewed.

Takes you forward to the next page in sequence.

Prints one or more topics. A dialog box prompts you to choose between printing the current topic and printing all topics in the currently selected book in the Contents tab.

Note: The printed document shows the actual size of the original graphics resulting in sub-quality of pagination.

Allows you to clear the history of links you have visited in this Online guide. To clear your visited links so they appear in their original (unvisited) colour, take the following steps:

  1. Click Options.

  2. Select Internet Options. An Internet Options dialog box is displayed.

  3. Click Clear History. A prompt asks whether you want to delete all items in your history file.

  4. Click Yes, then click OK to close the Internet Options dialog box.

  5. Click Options again.

  6. Select Refresh to refresh the links.

Allows you to control the size of the fonts.

Back to Top

Using the Navigation Pane

The navigation pane contains three tabs labeled Contents, Index, and Search. The following are explanations of these features:

Tab

Description

Presents a hierarchical, expandable/ collapsible table of contents. Following are the meanings of the symbols used:

 | A main topic (book) with subtopics that are not currently displayed. Click the icon to display the subtopics.
 | A main topic with subtopics that are already displayed. Click the icon to hide the subtopics.
 | A topic that has no subtopics beneath it. Click to display the topic.
hhglobe.gif (947 bytes) | A link to a document on the World Wide Web. Click to display the document.

A list of index entries. Type a term you are looking for in the box, or scroll through the list until you find a term that interests you. Double-click the term to display the topic.

Provides a full text search.

  1. In the search box type one or more words you want to find.

  2. Click List Topics.

  3. Scroll through the Topics list, and double-click the topic that interests you.

Back to Top

Using the Topic Pane

The topic pane displays the text of the current help topic.

Information or procedures that may result in possible loss of data or personal injury will be identified by one of the following symbols:

Symbols | Description
 | Software caution symbol that indicates possible loss of data.
 | Hardware caution symbol that indicates possible damage to equipment.
 | Indicates information about preventing injuries or fatalities

To clear your visited links so they appear in their original (unvisited) color, take the following steps:

  • Choose the Options button on the toolbar.

  • Select Internet Options.

  • In the Internet Options dialog box, click Clear History.

  • When the confirmation message appears, click OK.

  • In the Internet Options dialog box, click OK.

  • Select the Refresh button on the toolbar. If there is no Refresh button, select the Options button and then choose Refresh from the drop-down menu.

Back to Help on Help


_FCB

_FCB ---------- Returns the File Control Block (FCB) information for the currently OPEN file

Type

U/BL command and statement

Syntax

_FCB (b$,chan)

Arguments

b$ | A string variable which receives the file's FCB information. This string must be DIMensioned to at least 80 bytes.
chan | A numeric expression specifying the channel number on which the file was OPENed.

Description

The _FCB statement returns the File Control Block (FCB) information for the file currently OPEN on channel chan, in the b$ parameter. The string to receive the FCB must have been DIMensioned to at least 80 bytes. If the string is too small, Basic will generate a subscript error when it attempts to execute the _FCB statement.

The environment variable BBEXTENSION must be set to include SDOS in order to use this function.

Example

:

02000 REM Unpack and Display a File's FCB

02010 _FCB (FBK$,CHAN)

02020 LET NAME$=UCM$(FBK$[1,8]) \ UGRP$=FBK$[9,9]

02030 TYPE$=FBK$[13,13]

02040 LET X$=FBK$[18,18],FBK$[17,17],FBK$[16,16]

02070 LET SSEC=ASC(X$[1,3])

02080 LET X$=FBK$[21,21],FBK$[20,20],FBK$[19,19]

02090 LET NSEC=ASC(X$[1,3])

02100 LET X$=FBK$[24,24],FBK$[23,23],FBK$[22,22]

02110 LET MREC=ASC(X$[1,3])

02120 LET X$=FBK$[26,26],FBK$[25,25]

02130 LET RLEN=ASC(X$[1,2])

02140 LET X$=FBK$[30,30],FBK$[29,29] \ J=ASC(X$[1,2])

02150 STMA 11,J,MM,DD,YY

02160 LET CDAT=DD*10000+MM*100+YY

02170 LET X$=FBK$[33,33],FBK$[32,32],FBK$[31,31]

02180 LET LRECU=ASC(X$[1,3])

02190 LET X$=FBK$[36,36],FBK$[35,35],FBK$[34,34]

02200 LET FDEL=ASC(X$[1,3])

02210 IF TYPE$="T" THEN

02220 LET X$=FBK$[41,41],FBK$[40,40],FBK$[39,39],FBK$[38,38]

02230 LET NBOT=ASC(X$[1,4]

02240 END IF

02250 LET X$=FBK$[47,47],FBK$[46,46]

02260 LET EXTS=ASC(X$[1,2])

02270 LET X$=FBK$[50,50],FBK$[49,49],FBK$[48,48]

02280 LET NOACT=ASC(X$[1,3])

02290 LET X$=FBK$[52,52],FBK$[51,51] \ J=ASC(X$[1,2])

02300 STMA 11,J,MM,DD,YY

02310 LET LWDAT=DD*10000+MM*100+YY

02320 LET UDNO=ASC(FBK$[57,57])

02350 PRINT "File Name: ";NAME$

02360 PRINT "User Group: ";UGRP$

02370 PRINT "File Type: ";TYPE$

02380 PRINT "Starting Sector Number: ";SSEC

02390 PRINT "Number of Sectors: ";NSEC

02400 IF TYPE$="D" THEN

02410 PRINT "Maximum No of Records in File: ";MREC

02420 PRINT "Record Length: ";RLEN

02430 END IF

02440 IF TYPE$="I" OR TYPE$="J" THEN

02450 PRINT "Maximum No of Sectors in File: ";MREC

02460 PRINT "Block Length: ";RLEN

02470 LET X$=FBK$[28,28],FBK$[27,27] \ KLEN=ASC(X$[1,2])

02480 PRINT "Key Length: ";KLEN

02490 END IF

02500 PRINT USING "'Date of Creation: ',' / /',T0,D8.0",CDAT

02510 PRINT "Last Record Number Used: ";LRECU

02520 PRINT "First Deleted Record No: ";FDEL

02530 IF TYPE$="T" THEN PRINT "No of Bytes of Text: ";NBOT

02540 PRINT "No of Extents: ";EXTS

02550 PRINT "No of Active Records: ";NOACT

02560 PRINT USING "'Date Last Written to: ',' / /',T0,D8.0",LWDAT

02570 PRINT "Unit/Drive No: ";UDNO

02999 RETURN

:

See also

FCB$


Introduction

The User Guide describes how to use the U/BL software. It is divided into the following sections: