Installing and Customizing HP BASIC/UX 8.0

This chapter explains how to install HP HP BASIC/UX 8.0 on Series 700 workstations running the HP-UX version 10.01 operating system. It covers the following topics:

Preparing to Install HP BASIC/UX 8.0

This section provides the following information:

The HP BASIC/UX 8.0 Product Package

The HP BASIC/UX 8.0 product includes these components:

Where to Start the Installation

Where you start the HP BASIC/UX 8.0 installation depends on your current configuration:

  1. Install the HP-UX 10.01 operating system by following the documentation provided with HP-UX 10.01.
  2. Install HP BASIC/UX 8.0, following the instructions in this chapter.
  3. Install and configure the HP Standard Instrument Control Library (SICL) for use with HP BASIC/UX 8.0, following the instructions in Chpater 2.

  1. Update HP-UX to version 10.01 by following the documentation provided with HP-UX 10.01.

    NOTE Remove any previous versions of BASIC/UXx; before you update to 10.01.

  2. Install HP BASIC/UX 8.0, following the instructions in this chapter.

  3. Install and configure the HP Standard Instrument Control Library (SICL) for use with HP BASIC/UX 8.0, following the instructions in Chapter 2.

  1. Install HP BASIC/UX 8.0, following the instructions in this chapter.
  2. Install and configure the HP Standard Instrument Control Library (SICL) for use with HP BASIC/UX 8.0, following the instructions in Chapter 2.

Checking Your HP-UX Version Number

HP BASIC/UX 8.0 runs only on HP-UX 10.01, and not on previous HP-UX versions. If you are installing HP BASIC/UX 8.0 on an existing HP-UX system, check your current version of HP-UX. Log in and execute:


	uname -r

The version number is at the end of this release level string. For example, B.10.01 indicates version 10.01. If your current version is not HP-UX 10.01, update your system to HP-UX 10.01 by following the documentation provided with HP-UX 10.01 before you install HP BASIC/UX 8.0.

Prerequisite HP-UX File Sets

The following HP-UX file sets are required for installing HP BASIC/UX 8.0:

Ensure that your system has these file sets before proceeding with the HP BASIC/UX 8.0 installation.

Installing HP BASIC/UX 8.0 on HP-UX 10.01

This section explains how to install HP HP BASIC/UX 8.0 on a system running HP-UX 10.01. This installation uses the HP-UX software distributor (SD) tools and should take 20 to 30 minutes to complete. Verify that your system meets all the hardware and software requirements as described in the previous section before continuing with this installation.

The HP-UX software distributor (SD) install program (swinstall) is an interactive program that installs software from a CD-ROM depot, or from a special SD-UX directory on your local host or on some other host. The software distributor cluster program (swcluster) uses swinstall to install the software onto your cluster nodes. If you are not familiar with the SD-UX software distributor tools, see the Managing HP-UX Software with SD-UX manual, or the manual page for sd for additional instructions. If you have any questions while using the tool, use the online help for more information.

Follow these steps to install HP BASIC/UX 8.0 on HP-UX 10.01:

  1. Become the root user on the server for a diskless cluster or a stand-alone system.
  2. Insert your BASIC/UX 700 CD-ROM and mount it. See the mount(1m) man page for information on the mount command.
  3. Run the interactive HP-UX software distributor program:
    1. To install on a Series 700 standalone or Series 700 diskless server, execute:
      	/usr/sbin/swinstall
      
    2. To install for the clients of a Series 700 or Series 800 diskless server, execute:
      	/usr/sbin/swcluster -i -vvv
      

      The -i indicates interactive mode, and the -vvv indicates the level of verbosity.

  4. If you used the swcluster program, the program will prompt for you to select the alternate root path. The path is usually the following:
    	/export/shared_roots/OS_700
    

  5. The program lists the following fields:
    Source Host Name Lists the host you are installing from. If you would like to install from a different host, be sure to include the server IP address.
    Source Depot Path Specifies the source depot you wish to install from. If you are installing from a CD-ROM depot, list the directory the CD-ROM depot is mounted on (for example, /cdrom). If you are installing from a hard disk, list the directory path to the file sets (usually /var/spool/sw).
    Change Software View Specify All Bundles for the BASIC/UX 700 software.

    Change the fields above to reflect your installation and click on the [OK] button.

  6. The swinstall program reads the bundles available from the source depot. The HP BASIC/UX 8.0 software bundle will be displayed as follows:
    
    	E2045B   ->   C.08.00   HP BASIC/UX 700
    

  7. Install the HP BASIC/UX 8.0 product instead of the complete bundle (the bundle may also include other versions of BASIC/UX, which you do not need):

    1. Double-click on the HP BASIC/UX bundle so that the various product versions, HP BASIC/UX 8.0 and any other BASIC/UX versions, are displayed.
    2. Click on the HP BASIC/UX 8.0 product.
    3. From the Actions menu, select   Mark for Install.

  8. From the Actions menu, select Install (analysis) to begin the analysis process.

  9. The program performs an analysis to ensure the installation will be successful. When the analysis status reads Ready, click on the [OK] button to begin the installation. If the analysis fails, click on the [Logfile] button for information on why the analysis failed.

  10. If you used the swcluster program:

    1. The program asks if you would like to exit swinstall. Click on [YES].
    2. The software is installed on the cluster nodes, and the program exits. Note that if this is the first time the software is installed, the cluster clients will be halted.

    If you used the swinstall program:

    1. The program asks if you want to install the selected software. Click on [YES] to begin the installation.

    2. After the software is installed, the program specifies whether you have any NOTEs, ERRORs, or WARNINGs. If you do, click on the [Logfile] button to determine any necessary action. (See the next section for information on NOTEs, ERRORs, or WARNINGs.)

    3. When the status reads Ready, click on the [Done] button.
  11. When the loading process is complete, unmount your CD-ROM, remove the installation CD-ROM, and store it in a safe place. See the umount(1m) man page for information on the umount command. The HP BASIC/UX 8.0 software is now installed on your system.

The Logfile

To check on errors or warnings that might have occurred during the HP BASIC/UX 8.0 installation, review the log file generated by the swinstall program by selecting [Logfile] from the menu. Or, if you used the swcluster program, you can view the logfile by executing:


	tail -50 /var/adm/swcluster.log | more

Notes, Errors, and Warnings are defined as follows:

HP BASIC/UX 8.0 File Sets

When you install BASIC/UX, you add file sets to the HP-UX system. This section describes the file sets and the disk space they require. The sizes shown are approximate.

HP BASIC/UX 8.0 is composed of five file sets. The file sets are summarized in the following table.

HP BASIC/UX 8.0 File Sets
File Set Size Description

Runtime 4.8 MB Mandatory file set containing core BASIC/UX files, such as:
rmb
rmbclean
ipcclean
rmbtmr
rmbxfr
rmbkbd
rmbhil

It also contains font libraries and nls files.

CompiledSUBS 400 KB File set containing the CSUB Utility and files, such as:
librmb.a
csubdecl.h
rmbbuildc

Utilities 250 KB File set containing BASIC language utilities, such as:
BPLOT
GDUMP_R
LIF_UTIL

Manuals 15 KB HP-UX man pages.

Demonstration 550 KB Demos and examples from the manuals.

For a current list of the file sets installed on your system, execute:

	/usr/sbin/swlist -l fileset

Required SICL Filesets

To run BASIC/UX, you must install, at minimum, the SICL_RUN fileset (provided on the "HP I/O Libraries" CD-ROM). In addition:

For more information about rebuilding your kernel, refer to the following section, "Updating Your Kernel".

Updating Your Kernel

The BASIC/UX; swinstall or swcluster process does not automatically create a new kernel. BASIC/UX needs kernel drivers for SICL I/O and an enlarged message queue. Although this kernel modification is not mandatory, some features of BASIC/UX will be missing or unreliable using the an unmodified kernel. Therefore, after you run the swinstall or swcluster utility, you will probably want to create a new kernel.

This section first discusses the configurable parameters that affect BASIC/UX. Then, it explains the step-by-step procedure for creating a new kernel.

Important Kernel Parameters

BASIC/UX 700 requires the following kernel parameters. You should check that the value of each of the following three parameters is enabled (that is, set to 1). The values are set to one by default.

Parameter Value Description
mesg 1 System V messages
sema 1 System V semaphores
shmem 1 System V shared memory

NOTE
You can check or change the value of kernel parameters with the HP-UX System Administration Manager (sam) utility. To execute sam:

  1. Become super-user.
  2. Execute:
    
    /usr/sbin/sam
    

The following kernel parameters affect the performance of BASIC/UX 700. You should not reduce the values of these parameters below the recommended value unless you have a clear understanding of the parameter's effect on the system. BASIC/UX may not operate properly if you reduce any value below the specified minimum.

Parameter Default\Value Recommended\Value Minimum\Value Description
nproc 276*

(see text)*

default Max processes on system
maxuprc 50 90 32 Max processes per user
msgtql 120 256 128 Max number of queued messages
maxdsiz 64M default 2M Max data segment size
maxssiz 8M default 1M Max stack segment size
maxtsiz 64M default 4M Max text segment size
shmmax 64M default 1M Max shared segment size

* The default nproc value depends upon the number of users and clients served by the system. Larger systems will have a larger default value. Specifying a value smaller than the default is not recommended. Values larger than the default are recommended for systems running HP VUE.

NOTE
The only kernel parameters for which the default value is not sufficient are msgtql and maxuprc. A lightly loaded system with only one BASIC/UX process may operate properly with the default msgtql value. However, using the recommended value is important for reliable BASIC/UX operation on most systems.

Building a New Kernel

There are several different ways to build an HP-UX kernel. A detailed discussion of all the methods is beyond the scope of this manual. This chapter explains how to do this using sam. See Chapter 2 for details of doing this with the pilconf utility.

Running the HP-UX sam Utility

The System Administration Manager (sam) utility reads the parameters from your running kernel and allows you to edit those parameters to create a new kernel.

The following is a typical procedure for updating the kernel with sam:

  1. Login as superuser (root) and execute the command:
    	sam
    
    
  2. Double-click the [Kernel Configuration] icon.
  3. Double-click the [Configurable Parameters] icon. A list of parameters appears.
  4. Select the desired parameter. For example: msgtql.
  5. Select [Actions] ... [Modify Configurable Parameter... ].
  6. Make your change in the box provided. Your change is confirmed in the Pending Value column after you select [OK].
  7. Repeat the preceding three steps for any other parameters you wish to change.
  8. Select [Actions]... [Create a New Kernel].
  9. Answer [Yes] to the confirmation question.
  10. Wait for the kernel build to complete.
  11. Select [Continue Without Moving the Kernel Into Place].
  12. Select [OK].
  13. Exit sam.
  14. Proceed to Chapter 2 to create your new kernel. The preceding steps did not install a new kernel or add any I/O drivers. They simply created an accurate system file and built a new kernel.

Customizing Your Windows Environment for HP BASIC/UX 8.0

After you complete the installation process using swinstall or scluster, you can then customize BASIC/UX to perform optimally in its operating environment. This section describes typical customization tasks for the X Windows and HP VUE environments. For additional information, consult the HP Visual User Environment 3.0 User's Guide and Using the X Window System manuals.

The process of customizing BASIC/UX for its operating environment involves two categories of tasks:

Customizing X Windows To customize BASIC/UX for the X Windows environment, you can modify the color database, preallocate colormap entries, specify the default window's appearance, or change keyboard mappings.
Customizing HP VUE To customize BASIC/UX for the HP VUE 3.0 environment, you can add RMB icons to the VUE Front Panel and to your Personal Toolbox.

Customizing X Windows for HP BASIC/UX 8.0

While running BASIC/UX in your X Windows environment, you may notice that the colors on your screen change when you move the cursor in and out of the BASIC/UX window. The colors on your screen may also change while other applications are running. This color change can be disconcerting, and there is a way to keep it from happening.

A set of custom colors has been established for BASIC/UX operating in the X Windows environment. These custom colors imitate the colors that appear in BASIC/WS. You can set your colormap to imitate the BASIC/WS colors and, at the same time, stabilize the color-changing phenomenon by incorporating this set of colors into the X Windows colormap.

The procedure for configuring X Windows to preallocate the BASIC/UX custom colors involves two steps:

  1. Modifying the X Windows RGB color database.
  2. Preallocating the color entries in the X Windows colormap.

BASIC/UX uses the first 8 or 16 X Windows colormap entries, starting with entry number zero. The X Windows system allocates colors as application programs request them. If a BASIC/UX preallocated color is present in the X Windows colormap when that color is requested by another X Windows application, then that color is used in the other X Windows application and X Windows does not allocate another color. Hence, a uniform color environment is maintained across multiple applications when you preallocate the X Windows colormap entries with the BASIC/UX colors.

Be aware, however, that since BASIC/UX has the capability to dynamically change the colors it uses (using the SET PEN commands), it is possible that a BASIC/UX program will change the colors that it shares with other X Windows applications.

Modifying the X Windows RGB Color Database

Custom colors for BASIC/UX are not part of the standard X Windows colormap database. The RGB color database (in the rgb.txt file) associates valid color names with their RGB (red, green, blue) values.

Use the following commands to add the custom colors specified in the file rgb.rmb to the default RGB database for X Windows and to build the appropriate files needed by X Windows:

  1. Login as superuser (root).

  2. Merge the RMB colors by executing:
    	cat /opt/rmb/rmb8_0/newconfig/rgb.rmb >> /etc/X11/rgb.txt
    
    
    If you are using a gray scale display, execute:
    
    
    	cat /opt/rmb/rmb8_0/newconfig/gray.rmb >> /etc/X11/rgb.txt
    

  3. Run the rgb utility to generate a color map, as follows:
    	/usr/bin/X11/rgb   <   /etc/X11/rgb.txt 
    

Preallocating the Entries in the X Windows Colormap

Once you have added the custom BASIC/UX colors to the RGB database by following the procedure given in the previous section, you can configure the system to preallocate the colormap entries. To have the system preallocate the colormap entries, include one of the following two lines in your $HOME/.x11start file:

	/opt/graphics/common/bin/xinitcolormap -c 16 -f /opt/rmb/rmb8_0/newconfig/xrmbcolormap

	/opt/graphics/common/bin/xinitcolormap -c 8 -f /opt/rmb/rmb8_0/newconfig/xrmbcolormap

The first line allocates the first 16 entries in the X Windows colormap, while the second line allocates the first 8 entries.

NOTE
By including the xinitcolormap lines in your $HOME/.x11start file, you preallocate the X Windows colormap entries before any other X clients are started.

For gray scale displays, include one of the following lines in your $HOME/.x11start file:

	/opt/graphics/common/bin/xinitcolormap -c 16 -f /opt/rmb/rmb8_0/newconfig/xrmbgraymap

	/opt/graphics/common/bin/xinitcolormap -c 8 -f /opt/rmb/rmb8_0/newconfig/xrmbgraymap

The xinitcolormap command line option -c specifies how many colormap entries to select from the file specified by the -f option. When you use -c 16, ensure that at least 16 color map entries are available on the system. If you desire to preallocate only the first eight colormap entries, use the option -c 8, instead.

If you are running HP VUE, add the appropriate xinitcolormap call to the file /usr/vue/config/Xsession. You will find a sample Xsession file which incorporates this change in /opt/rmb/rmb8_0/newconfig.

Specifying the HP BASIC/UX 8.0 Window's Appearance

You can specify the initial appearance of the BASIC/UX window using the X Windows custom colors that you preallocated earlier. For example, you can specify green text on a black background. Typically, you specify colors and other window attributes in the $HOME/.Xdefaults file.

In the example file, /opt/rmb/rmb8_0/newconfig/d.Xdefaults, you will find lines similar to the following two lines:


	Rmb*background:         black
	Rmb*cursorMode:         underscore

These lines specify the BASIC/UX window background color and cursor appearance, respectively.

NOTE
Once it is running, BASIC/UX does not allow you to interactively resize its main window or any of its subordinate windows. However, you can change the size and position of the BASIC/UX window before you run BASIC/UX. X Windows -geometry specifications are supported in BASIC/UX.

The same is true for programmatically created windows. That is, after you execute a CREATE WINDOW command, you cannot resize that window.

Changing Keyboard Maps

BASIC/UX supports the following keyboards for HP workstations or 700/RX terminals:

HP Keyboards Supported in X Windows
Model Number Interface Keyboard Type
HP 46021A/B HP-HIL ITF
HP C1429A HP-HIL PC-101
HP C1405A PS/2 PC-101
HP A2840B DIN PS/2

In revision 8.0, BASIC/UX; has added a new "daemon" for keyboard support. You may prefer to use the new daemon's capabilities to handle some of these keyboards. If so, see "Enhanced Keyboard Handling" in this chapter for details.

NOTE
PS/2 DIN keyboards are only supported on HP9000 Series 712, 715, or 743 computers running X Windows. PS/2 DIN keyboards are not supported on 700/RX or 700/X terminals.

The PC-101 and PS/2 DIN keyboard types cannot generate some of the functions required by BASIC/UX (for example, Insert Line) unless the keys are "mapped" from what is engraved on the keyface to the correct function. You will be using the X utility, xmodmap, to map the PC-101 and PS/2 DIN keys to the correct functions.

If you are using an HP C1405A keyboard, note that you'll need to know which keyboard interface you have so that you can perform the appropriate keyboard mapping, and so that you can select the correct value for the -K option to the rmb command. For more information, refer to the rmb online man page (execute man rmb).

To perform the key mappings necessary to operate BASIC/UX in X windows, execute the X utility xmodmap with one of two files: xmodmap.PC.HIL or xmodmap.PC. These files are in /opt/rmb/rmb8_0/newconfig (they were placed there during the BASIC/UX installation). For example, the following command:

	/usr/bin/X11/xmodmap /opt/rmb/rmb8_0/newconfig/xmodmap.PC.HIL

maps certain keys of the HP HIL keyboard so that they function as specified in the xmodmap.PC.HIL file.

Or, if you have a PS/2 DIN keyboard, the following command:

	/usr/bin/X11/xmodmap /opt/rmb/rmb8_0/newconfig/xmodmap.PC

maps certain keys of the PS/2 DIN keyboard so that they function as specified in the xmodmap.PC file.

You may wish to place either of these commands in your $HOME/.x11start file, in the /usr/vue/config/Xsession file (HP VUE), or in your $HOME/.xsession file (700 X terminals).

By studying the xmodmap.PC.HIL and xmodmap.PC files, you will understand how to customize the keyboard mappings to your own taste.

Customizing HP VUE 3.0 for HP BASIC/UX 8.0

You can customize HP VUE 3.0 for BASIC/UX by creating three different types of BASIC/UX icons:

Customizing RMB Icons for a Workspace

When you iconify the BASIC/UX window, a BASIC/UX icon appears on your current workspace screen. You can choose the size (one of three) for the RMB icon that your workspace displays.

To set the size of the RMB icon that is displayed in the workspace, specify the proper bitmap file name as the window manager's iconImage X resource. Specify the bitmap file name in one of two ways:

Creating an RMB Icon for the Front Panel

You can customize HP VUE 3.0 by adding an RMB icon (control) to the Front Panel.

NOTE
If you have already customized your vuewmrc file, do not destroy it by copying the sys.vuewmrc file in the following procedure. Instead, locate the "CONTROL Rmb" information in the sys.vuewmrc file and merge it into your existing vuewmrc file.

To add an RMB icon to the VUE Front Panel, define the control in your vuewmrc file, which consists of an RMB control and the two actions START_RMB and RUN_RMB in your vuewmrc file. Be sure to save copies of the original files before you use the commands in the following procedure.

Use the following commands to add the RMB icon to the VUE Front Panel, the START_RMB and RUN_RMB icons to your Personal Toolbox:

	cp /opt/rmb/rmb8_0/newconfig/sys.vuewmrc  $HOME/.vue/vuewmrc
	cp /opt/rmb/rmb8_0/newconfig/START_RMB.vf  $HOME/.vue/types
	cp /opt/rmb/rmb8_0/newconfig/RUN_RMB.vf  $HOME/.vue/types
	cp /opt/rmb/rmb8_0/newconfig/START_RMB  $HOME/.vue/types/tools
	cp /opt/rmb/rmb8_0/newconfig/RUN_RMB  $HOME/.vue/types/tools

The last two files copied are empty, however, they are necessary for the RMB icons to appear in your Front Panel and Personal Toolbox.

Using the Front Panel RMB Icon

If you have logged in with HP VUE 3.0, your VUE Front Panel should appear at the bottom of the screen. If you have a factory preinstalled BASIC/UX configuration, there will be a BASIC/UX ("RMB") icon at the left-hand side of the Front Panel, as shown below:

You can use the Front Panel RMB icon in one of two ways:

Creating and Using RMB Icons for the Personal Toolbox

If you executed the steps in the previous section or have a factory pre-installed BASIC/UX system, START_RMB and RUN_RMB will appear in your Personal Toolbox. To start BASIC/UX, you can either:

For example, the RUN_RMB icon for Personal Toolbox is created as follows:

  1. Optional: Create custom icons, using the IconEditor tool in the Personal Toolbox.

  2. Open the General Toolbox, and select Utilities. Use CreateAction to create an "RMB" button. Enter the [Name] as RUN_RMB.

    NOTE
    It is a good idea to leave the CreateAction window open until you have tested your new icons. It is easy to make changes and select [Apply] while the utility is still running. When you are satisfied with your new icon, select [Close] at the bottom of the CreateAction window.

  3. Enter a [Command Line]. The following example invokes BASIC/UX in the background, using X-graphics, and takes one parameter. All other rmb command line options are allowed.
    
    	/usr/bin/sh -c "/opt/rmb/rmb8_0/bin/rmb -X $1 &"
    

  4. Choose the [No Output] Window Type.

  5. Type an appropriate prompt into the [Filename Prompt] entry area. For example:
    
    	Enter the Name of a BASIC program to run.
    

  6. Optional: If you have created a custom large icon for BASIC/UX, put its full path name in the [Large Icon] field. Alternately, select an existing icon from the /usr/vue/icons directory.

  7. Optional: If you have created a custom small icon for BASIC/UX, put its full path name in the [Small Icon] field. Alternately, select an existing icon from the /usr/vue/icons directory.

  8. Optional: Put your choice of description into the [Description] field.

  9. Click on [Apply].

After completing the procedure above, the new icon RUN_RMB should appear in your Personal Toolbox window.

When you double click the RUN_RMB icon, a dialog will appear asking you for the name of a program file to execute. After you click [OK], BASIC/UX will start and run the program, if you provided a valid filename. If you drag a program file onto the RUN_RMB icon, BASIC/UX will start and run the program.

When you double click the START_RMB icon, BASIC/UX will start, after a brief delay.

Customizing Your BASIC/UX Configuration

When you start BASIC/UX, it looks for a configuration file. The commands in the configuration file set certain attributes of BASIC's environment. such as graphics buffering, process locking, workspace size, available interfaces, and more. When BASIC/UX sets its default configuration, it first looks for the global configuration file:


	/etc/opt/rmb/rmb8_0rc

Next, BASIC/UX looks for the user's configuration file:


	$HOME/.rmbrc

The configuration file is a text file that can be edited by HP BASIC/UX or any system editor such as vi. Any specifications in the local configuration file will override the global specifications.

A template configuration file is available for you to customize. Copy it to your home directory, and rename it to .rmbrc. This template is:


	/opt/rmb/rmb8_0/newconfig/rmbrc

For example, to copy the file to /home/leslie using BASIC/UX, execute:


	COPY "/opt/rmb/rmb8_0/newconfig/rmbrc" TO "/home/leslie/.rmbrc"

To copy the file to /home/leslie using HP-UX, execute:


	cp /opt/rmb/rmb8_0/newconfig/rmbrc /home/leslie/.rmbrc

BASIC/UX does not lock the global and local rmbrc files. The issue of security is left to the user. It is suggested that the permissions be set to 644 or 444, and the global rmbrc file should be owned by root to prevent unauthorized access. The only requirement of permissions is that users have read permission on the global and local rmbrc files.

What Variables Can Be in the Configuration File?

The configuration file contains declarations and/or assignments of various BASIC/UX environment variables. For example:


	10 !#  This is a sample .rmbrc file
	20 !interface 7;autolock
	30 !errormode=off
	40 !workspace=1m
	50 !shl_search /home/leslie/libs
	60 !shl_load /opt/rmb/rmb8_0/lib/librmb8_0.sl
	70 !#  End of sample .rmbrc file

Details about all configuration variables follow this summary table.

Global Configuration Variables
Name of Variable Range of Values Default Value Description

autostart pathname n/a Pathname of an autostart file.

bind_time load

prerun

run

load Time at which to resolve references in a shared library.

csub_math_except on, off on To disable the math exceptions before calling a CSUB.

errormode on, off on Generate error messages for BASIC Workstation, BASIC/UX compatibility.

graphics_buffer on, off on Turn on graphics buffering.

hfs_buffer on, off on Turn on HFS file system buffering.

keep_shared_libs on, off on To keep shared libraries loaded when the last CSUB that references them is deleted.

plock all, t, d, w n/a Lock text area, data area, workspace or all of BASIC/UX into memory (any combination is valid).

selective_open on, off off Indicates that only specified interfaces should be opened.

kbd_daemon rmbkbd, rmbkbdx rmbkbd (except unknown keyboard) Selects the old rmbkbd or new rmbkbdx daemon.

keymap See samples in /opt/rmb/rmb8_0/

newconfig/keymaps

ITF configuration (46021 A/B) Defines binding between a command to BASIC and a key on the keyboard.

underflow_mode error

fastmode

ignore

error Specifies the behavior when floating point underflow is detected.

workspace 64K to shmmax value 1M Size of BASIC/UX workspace (integer values only).

The following sections provide more details on the configuration variables for BASIC/UX, as well as some additional statements you can add to the configuration file.

All the following rmbrc examples show an arbitrary line number created using the BASIC/UX EDIT mode. This example line number is not required and does not change the effect of the example.

Running an Autostart Program (autostart)

If you want an autostart program, you can specify the file with autostart. An example .rmbrc line using the program /home/leslie/AUTOST is:


	50 !autostart=/home/leslie/AUTOST

Resolving External References (bind_time)

When CSUBs are loaded into a BASIC/UX program, there may be some references to external procedures and data. The resolution of these references is referred to as "binding." BASIC/UX 700 allows the time of binding to be delayed, thereby allowing a trade off between performance and flexibility. See Developing CSUBs for HP BASIC/UX 700 for more information on binding.

55 ! bind_time=load  (default) Binding is to occur at load time for maximum performance.
55 ! bind_time=prerun  Perform binding at pre-run time.
55 ! bind_time=run  Perform binding at run time for maximum flexibility.

Enhanced Keyboard Handling

This section covers the following topics:

Overview

BASIC/UX 700 version 8.0 allows you to use many "generic" X server keyboards.

For example, suppose you want to work on a Sun workstation, and rlogin to a Series 700 computer. You would run BASIC/UX on the Series 700, and display its output to an X window on your Sun workstation.

Prior to version 8.0, this was not possible because BASIC/UX could not work with keyboards it did not specifically support. For example, it might mis-identify the keyboard language, assuming you were at a US ASCII keyboard rather than a Canadian French keyboard. Or you might not be able to find a Clear Display key.

With version 8.0, two new capabilities have been added:

NOTE
Be aware that even though you may be able to make an unsupported keyboard work correctly for BASIC/UX 8.0, there is no guarantee that the display or other components of the X-server will be compatible.

The Keyboard Daemons

BASIC/UX 8.0 supports two keyboard daemons: the "old" rmbkbd and the "new" rmbkbdx. These daemons are automatically invoked processes that receive your keystrokes and sent them to rmb to be displayed as text or to execute commands.

The daemons work as follows:

How the Daemons are Invoked

If you are using a keyboard that BASIC/UX does not recognize, rmbkbdx will always be invoked, even if you request the old daemon. This is because the older daemon is unreliable with unsupported keyboards.

If you are using a previously supported keyboard, you can choose which daemon BASIC/UX is to use by one of the following methods:

Remapping the Keyboard

The rmbrc file determines how your keyboard is remapped. Note that the term "rmbrc file" refers to either:

This section explains how to develop that file.

When using an unsupported keyboard, you may not be able to find the key that performs a needed function (such as Clear Display). Be remapping your keyboard, you may be able to remap that function to use a convenient key.

When you are using rmbkbdx, you have the ability to remap some of the keys on your keyboard (the non-alphanumeric keys) so that the keyboard is more easily used with BASIC/UX 8.0. To remap the keys, you insert the KEYMAP command in your rmbrc file.

NOTE

  • The KEYMAP command cannot remap alphanumeric or other "printable" keys, nor is it intended to support non-US ASCII language remapping. If you need to remap alphanumeric keys, use X's xmodmap(1) facility. For non-US ASCII keyboards, X servers usually do an adequate job of correctly matching keys to characters. If that is not the case, use xmodmap.

  • See the "Technical Background Discussion of Keyboard Mapping" for details concerning special translations of X keys.

Follow these steps to remap your keyboard:

  1. Understand the KEYMAP syntax and function names.
  2. Determine what values to use in your rmbrc file.

These steps are explained in the following sections.

Understanding the KEYMAP Syntax and Function Names

Before you attempt to modify your rmbrc file, we recommend you become familiar with the following:


	KEYMAP function_name symbol_value modifier_value # optional comment

         For example:


	KEYMAP Clear_Display 0xff0b 0x0  # same as 46021 mapping

       This is the syntax you will use in your rmbrc file.

There are currently over 80 different function names. For information on them, refer to:

/opt/rmb/lib/keymaps, a directory of keymap files that contain definitions for all of the possible function names.

/opt/rmb/lib/keymaps/ITF.EXAMPLE, a file that contains KEYMAP commands. The commands correctly map an ITF (46021A/B) keyboard to the same values as used in the standard rmbkbd daemon (with the exceptions stated in "Limitations of Remapping"). You may change the commands in any keymap file as you wish, but there are some rules and limitations to remember.

Determining the Symbol and Modifier Values to Use

The /opt/rmb/rmb8_0/bin/rmbksym program helps you discover the symbol and modifier values returned by your X server when you press a key. To use this program:

  1. Log in to your Series 700 computer from your X server.

  2. Export your display so that output is displayed on your X server.

  3. Perform the appropriate xhost command on your X server to allow the Series 700 to create a window on your computer. For example:
    	xhost = Series_700_hostname
    

  4. Run rmbksym on your Series 700 computer:
    	/opt/rmb/rmb8_0/bin/rmbksym 
    

    NOTE
    If you need to use xmodmap to run BASIC correctly, make sure you execute the appropriate xmodmap command exactly once before you execute rmbksym.

  5. Bring the focus to the rmbksym window. (Do not click in the window, as this exits the program.)

  6. Press the key on your keyboard for which you want keymap information. The output will appear in the window from which you started rmbksym (this window will contain a running list of the output) and in the rmbksym window (where the output is overwritten the next time you press a key). The output will look like this:
    
    	Keysym: 0x1000ff00,  modifiers: 0x0
    

    If the key produced a printable character, the character is printed at the end of the above line. For example:

    	Keysym: 0x61,  modifiers: 0x0  a
    

  7. Use this information to assign the key you just typed to a BASIC/UX function name. For example, you would insert a line like the following in your rmbrc file:
    
    	KEYMAP Clear_Display	0x1000ff00	0x0  # DEC DXK_Remove
    

    This would assign that key the function of clearing the BASIC/UX display window.

    Note that if 0x1000ff00 0x0 is already assigned to a KEYMAP function, you would need to move that functionality to another key/modifier pair. No one key combination can map to more than one function name. This is further explained in "Rules for Remapping".

    Adding a comment describing the physical key may help you remember later which keycap the mapping involves.

  8. To exit rmbksym, click in the rmbksym window.

NOTE
rmbksym can execute only on HP-UX Series 700 computers.

Limitations of Remapping

Keep in mind the following limitations as you remap your keyboard:

Rules for Remapping

Viewing the Current Mapping

You can request that BASIC/UX dump the current keymap information in the form of a text file. This can be helpful in choosing good mappings, documenting the mapping you have selected, and sorting out inconsistencies in mappings.

To request a textual dump of the current keymapping, place ; DUMP after the KBD_DAEMON command in /etc/opt/rmb/rmb8_0rc or $HOME/.rmbrc. For example:


	1000! KBD_DAEMON = RMBKBDX; DUMP

This creates /tmp/rmbkmap.pid, a text file that contains the keymappings used for that session of BASIC/UX. The pid extension refers to the process ID of rmb. The process ID is the number that appears on your hpterm window after you execute BASIC/UX in the background (with a trailing &). For example:

         $ rmb &

        [1]             21869

In this case, HP-UX assigned the process ID 21869 to rmb. If you have requested a dump of the keymappings, it will appear in /tmp/rmbkmap.21869. When experimenting with keymaps, run BASIC/UX in the background, as it is easier to find the process ID that way.

The format of the rmbkmap.pid file is suitable for attaching to your rmbrc file, because it contains correctly formatted KEYMAP statements.

NOTE
When you exit BASIC/UX, another execution of rmb may be assigned the same process ID as the session you just quit, and thus may overwrite the rmbkmap file. If you want to ensure that your keymap file stays intact for extended periods, you should copy it to another location

Technical Background Discussion of Keyboard Mapping

For the alphanumeric keys, BASIC/UX uses the natural X translation -- the same one as you see in a typical program such as xterm or hpterm. This means that whenever your X server returns a printable, non-CTRL character from a keystroke, BASIC/UX uses that character without modification. If a key is not intended to produce printable characters, the X server usually does not produce any characters for BASIC/UX, sending only a "KeySym" (key symbol) and "state" (whether Shift is pressed, etc. -- in other words, the modifier's value). In that case, BASIC/UX attempts to match the KeySym and state to a KEYMAP "symbol value" and "modifier value".

If the X server returns a printable character and you held down the CTRL key while pressing an alphanumeric key, BASIC/UX uses the X server character value mod 32, which is in the control character range.

Some X servers return characters in the control range when the user is not pressing the [CTRL] key. These are treated as special by BASIC/UX, and the key symbol and state are checked against the KEYMAP mappings for special meanings. If there is no special meaning, the control character is used as is.

If your X server returns a control character (non-printable) when you press a non-alphanumeric key together with [CTRL], BASIC/UX first checks to see if the key has been remapped. If so, it uses the remapped value if available. Otherwise, it uses the value given by the X server. A number of control characters have special meanings to BASIC/UX, and this way of handling them preserves their meanings.

Math Exception Handling for CSUBs (csub_math_except)

The "natural" mechanism for handling floating point exceptions in C, Pascal, and FORTRAN is to return the special IEEE floating point values infinity, NaN (not a number), etc. BASIC/UX 700 normally traps such exceptions and issues a BASIC error 21. This variable controls whether these exceptions are enabled within CSUBs. For more information, see the Developing CSUBs for HP BASIC/UX 700 manual.

75!sub_math_except=on (default) Exceptions are trapped and propagated to the BASIC program as error 21
 75!csub_math_except=off  BASIC/UX 700 will disable the math exceptions before calling a CSUB. The CSUB should ensure that the special floating point values are not returned to BASIC. This would lead to unpredictable results. The exceptions may be re-enabled inside the CSUB as needed.

Generate Compatibility Error Messages (errormode)

If you port programs created on BASIC Workstation systems, you may have some errors. For example, some commands (such as LOAD BIN) are not supported on BASIC/UX. This controls whether such errors are reported or silently ignored.

60 ! errormode=on  (default) Error messages are generated.
60 ! errormode=off  Does not generate error messages This is equivalent to the -e command line option.

Graphics Buffering (graphics_buffer)

When using graphics, you can choose to have graphics buffering on or off:

70!graphics_buffer=on (default) The image is faster than when off, but it could be choppy when an image moves on the screen.
70!graphics_buffer=off  The image is slower than when on, but it is smoother when the image moves on the screen.

HFS File System Buffering (hfs_buffer)

This variable determines when data is written to an HFS disk:

80!hfs_buffer=on  (default) Saves data in a buffer and writes to a disk periodically. Makes system operations faster, but a greater amount of data could be lost if a power failure occurs, or the system is not properly shut down.
80!hfs_buffer=off  Writes data to the buffer, then immediately to the disk. OUTPUT performs much slower.

Retaining Shared Libraries (keep_shared_libs)

The executable object code for CSUBs resides in shared libraries that are dynamically loaded into BASIC/UX 700. The default behavior for BASIC/UX is to keep these libraries permanently loaded as part of the program. This can cause a significant amount of swap space to be allocated to BASIC/UX for as long as it executes. For systems with limited swap space, it may be desirable to reclaim the memory space used by these shared libraries when they are no longer needed. When the keep_shared_libs variable is set to off, BASIC/UX will unload shared libraries when the last CSUB that references them is deleted.

65!keep_shared_libs=on  (default) Shared libraries are permanently loaded.
65!keep_shared_libs=off  BASIC/UX 700 will unload shared libraries when the last CSUB that references them is deleted.

Locking BASIC/UX in Memory (plock)

The plock variable can improve BASIC/UX response time by reducing or eliminating swapping of the BASIC/UX process. There must be sufficient RAM available to hold any locked portions. Note that the performance of other processes can be adversely affected if too much RAM is used to hold a locked process. To lock the text area, data area, workspace, or all of BASIC/UX into memory:

90 ! plock=all Locks all of BASIC/UX into memory.
90 ! plock=t Locks the text area into memory.
90 ! plock=d Locks the data area into memory.
90 ! plock=w Locks the workspace into memory.

Any combination of t, d, or w is valid (for example, plock=td). Process locking can also be specified by the -l command line option.

Selective Opening of I/O Interfaces (selective_open)

The default mode for BASIC/UX is to open all I/O interfaces and reset them at boot time. That mode can cause BASIC/UX to interfere with the I/O operations of another process. You can use the selective_open statement to limit BASIC/UX to opening only those interfaces specified in an interface statement.

100!selective_open=off (default) BASIC/UX attempts to open all I/O interfaces.
100!selective_open=on Specifies that BASIC/UX is to open only interfaces which are specified by an interface statement in the environment file.

Controlling Underflow Handling (underflow_mode)

Series 700 computers sometimes generate an underflow for intermediate floating point operations. BASIC/UX provides several different mechanisms for handling floating-point underflows.

110 !underflow_mode=error (default) Generates an error 21 for any underflow. This will limit the range of many mathematical functions. (Refer to &langref; for moreinformation.)
110!underflow_mode=fastmode Fastmode is functional only on hardware that supports this mechanism. Fastmode substitutes a value of 0.0 whenever an underflow is detected.
110 !underflow_mode=ignore Specifies that all underflows are to be ignored. Using the ignoremode may result in denormalized numbers, numbers that are less than MINREAL.

Setting Size of BASIC/UX Workspace (workspace)

If you commonly run large BASIC/UX programs, you can get a workspace larger than the 1 megabyte default by using the .rmbrc file.

	120 ! workspace=2M(default=1M)

Workspace size can also be specified by the -w command line option.

Automatic Interface Locking and Mapping (interface)

Establish automatic locking for an I/O interface.

Determine the select code of the interface, and include this in the .rmbrc file:


	130  ! interface select_code; [option]

where option is one of the following:

	autolock
	normal

If another process has a target interface locked, autolock will timeout when BASIC/UX starts, and the bootscreen will display an error message such as:

	AUTOLOCK failed

The most common instance is when multiple BASIC/UX processes are started with autolock or autoburst in their configuration file.

Select Code Aliasing (interface)

You can use the BASIC/UX configuration file to map a SICL logical unit to a virtual select code for use within BASIC/UX.

BASIC/UX 700 uses, by default, the same select code number as the SICL LU number, which is specified in the file /etc/opt/sicl/newconfig.cf. You can re-map select code numbers to meet your own particular needs.

To map the SICL LU 9 to select code 17:

      160 ! interface 17=9; [option]

The optional modes for these statements are normal and autolock, as appropriate for the interface.

The BASIC/UX bootscreen indicate select code aliasing. The I/O configuration lines appear as follows:

       card_type at PS->VS ...

where PS is the physical select code or SICL LU and VS is the virtual select code within BASIC/UX. If an interface has not been aliased, then the PS and VS fields will be the same.

Support of the HP SICL/LAN Interface (interface)

To configure a remote, LAN-gatewayed interface with BASIC/UX 700, include the following in the .rmbrc file:


	interface vs="lan_symname[hostname or IP_addr]:remote_symname";
Where: Represents:
vs The virtual select code of the remote interface to be used in your BASIC/UX program.
lan_symname The LAN interface's symbolic name.
hostname or IP_addr The HP-UX hostname or IP address of the server machine (where the remote interface is installed).
remote_symname The symbolic name of the remote interface to be accessed over LAN.

The following are some example .rmbrc file entries for LAN-gatewayed addresses of remote interfaces.

For more information about configuring the HP SICL/LAN interface for use with BASIC/UX 700, please refer to Chapter 2. To use the SICL/LAN interface, refer to "The HP SICL/LAN Interface" chapter in the HP BASIC Interface Reference.

Mapping an MSVS to an HFS Directory (disk)

If you have programs that access mass storage devices with the volume specifiers, you can map a volume specifier to an HFS directory with an entry such as:


	10 ! disk scba[,volume,unit] = directory_name
Where: Represents:
scba Select code × 100 = bus address
volume The volume number (optional; use the comma if you include this)
unit The unit number (optional; use the comma if you include this)
directory_name An HFS directory.

To map a device on select code 7, bus address 2, volume 1, mounted under /disk1, execute:


	10 ! disk 702,1 = /disk1

Mapping an MSVS to a SCSI Device (disk)

For BASIC/UX to access LIF file systems on SCSI devices, BASIC/UX must know the mass storage volume specifier for the device. There is no direct mapping between device files and BASIC/UX select codes. Therefore, you must provide the mapping in a disk statement. The following example statement creates a virtual mapping of the device file /dev/scsifloppy to the BASIC/UX address 1402.


	10 ! disk 1402 = /dev/scsifloppy # map to virtual select code 14

You can then initialize this disk with the following statement:


	INITIALIZE ":,1402"

The virtual select code you specify must not conflict with an I/O select code (either direct or remapped).

Adding Shared Library Search Paths (shl_search)

In BASIC/UX 700, CSUBs are implemented using shared libraries. These libraries may reside anywhere within the file system and are dynamically loaded when the CSUBs are loaded. To locate the shared libraries, BASIC/UX 700 searches a list of predefined directories. (Refer to the Developing CSUBs for HP BASIC/UX 700 manual for the list of predefined directories.) If the shared libraries are kept in directories that are not in this list, then you must define additional paths for BASIC/UX 700.

To specify additional paths in a configuration file, include lines in the file that have the following form:


	180  ! shl_search directory1
	190  ! shl_search directory2

The paths you specify are searched in the order that they appear in your configuration file. Shared library search paths can also be added by the -S command line option.

Loading Shared Libraries at Boot-Time (shl_load)

You can write CSUBs for BASIC/UX 700 that will call routines in system shared libraries. These libraries must be loaded before the CSUB executes. BASIC/UX 700 contains many shared libraries, and all of the routines in these shared libraries are available to CSUBs. (Refer to the Developing CSUBs for HP BASIC/UX 700 manual for a list of the shared libraries.)

When you need a system shared library that is not already in BASIC/UX 700, you can load it by including lines in your configuration file that have the following form:


	200  ! shl_load  library1
	210  ! shl_load  library2

The libraries you specify are loaded in the order that they appear in the configuration file, after all search paths have been added (see the earlier section "Adding Shared Library Search Paths"). The order in which the libraries appear is important because the libraries are loaded with immediate binding, that is, all references must be satisfied at load time.

Customizing the Kernel to Increase Workspace Size

If you need to set your workspace larger than 64 megabytes, you may encounter problems when trying to boot BASIC/UX. For example, you may see a message such as:


	rmb: shared memory size exceeds kernel limits

The information covered in this section provides you with an explanation and solution to this problem.

BASIC/UX places its workspace in a shared memory segment. HP-UX imposes some limits when dealing with shared memory segments. The kernel parameter shmmax defines the maximum size of any shared memory segment. The BASIC/UX workspace cannot be larger than this parameter. The default size of shmmax is 64 megabytes. Any changes to shmmax must be made by reconfiguring the kernel.

The BASIC/UX Process Space

The following diagram shows the HP-UX 10.0 memory layout of the HP BASIC/UX 700 process:

A BASIC/UX 700 Process

Enlarging the Kernel's shmmax Parameter

Before trying to enlarge your workspace, please ensure that you have correctly configured your kernel to run BASIC/UX with the default workspace of one megabyte. This section assumes you have already read and followed all the instructions from the "Updating Your Kernel" section earlier in the chapter. If you are experiencing problems running BASIC/UX with a small workspace, those issues must be settled before you attempt enlarging the workspace.

Notes On Very Large BASIC/UX Workspaces.

BASIC/UX places its workspace in a shared memory segment. The size of this shared memory segment is determined by the command line workspace argument (-w), or by the workspace parameter in your .rmbrc file. In HP-UX 10.0, the maximum size of any shared memory segment is determined by the shmmax kernel parameter. The default limit of this parameter is 64 megabytes. The absolute limit for this parameter on any system is two gigabytes.

Although a two gigabyte BASIC/UX workspace may sound exciting, the total BASIC/UX process size (including code, data, heap, Starbase shared memory, BASIC/UX workspace, and process stack) is always limited by the amount of swap space available on your system. Thus, very large BASIC/UX workspace sizes will consume very large amounts of swap space.

The total size of all running processes must never exceed the available swap space. On a system running VUE, X11, and BASIC/UX, you might expect the maximum BASIC/UX workspace size to be roughly:

(total swap space) - (50 megabytes)

On a system with 90 MB of swap space, you might be able to run a BASIC/UX process with about 40 MB of workspace. For details about creating and managing swap space, refer to the System Administration Tasks manual.

Use sam to set shmmax to the desired value and rebuild the kernel, then reboot so that the change takes effect.