t3:2:respawn:d3 -n pick0 -u /t20256,s

#

# Copyright (c) TigerLogic 2009. All rights reserved

# Tue Feb 25 10:48:01 2009

#

name OS pick0

nice 0

core 51241 10

npibs 16

nphts 10

hostauthentication on

basic 8192

brkchr 00

escchr 1b

absbase 18

abssize 708

abslock on

blkfid 2

bootsleep 10

flush 10

flushers 5

dwqnum 256

crange 10 20

clocal on

serialrange 21 30

telnetrange 31 40

user joe

groups marketing sales

disk /dev/hda4 0 427392 # disk 0

tape /dev/fd0H1440 500 f lq # tape 0

tape /dev/fd0H720 500 f ld # tape 1

tape /usr/lib/pick/ab 500 p lx # tape 2

tape /usr/lib/pick/dt 500 p lx # tape 3

heading section (# commented)

Displays the copyright and the last date and time of creation/modification of the configuration file.

name OS vm.name

Name of the D3 virtual machine. If the virtual machine exists, its configuration file is read and displayed. The default name is pick0. OS is your operating system.

nice priority

Signed value adjusts the relative scheduling priority of the D3 process compared with other regular UNIX processes. A negative value returns a higher priority. A positive value returns a lower priority. Legal values are -19 (highest priority) to +20 (lowest priority). The default value is 0.

core memory key

Virtual machine memory usage and key.

• The memory parameter is the amount of shared memory (in Kilobytes) the D3 process allocates for itself while the virtual machine is running. Low values may result in poor performance of the D3 process due to swapping. High values can result in poor performance of other UNIX processes due to inadequate remaining memory. The core parameter should be reduced when running FlashBASIC applications on a system. To determine an appropriate size, boot the system, bring up all users in FlashBASIC, and run the buffers command with the (sl options. The default values are 37.5% of the total memory for AIX and 12% of total memory for Linux.

NOTE—To get an estimate of the core size required for reasonable performance, take the reference number (not the percentage, but the larger number before it), multiply it by the frame size, and then divide by 8192. Shut down the D3 virtual machine, reset the parameter, and then reboot.

• The key parameter is the virtual machine key. This number, in hexadecimal, is a unique identifier for this particular D3 virtual machine. Each virtual machine must have its own unique identifier. Therefore, if several D3 virtual machines are running on the system, this identifier must be changed for each one. The default value is 10.

WARNING—Changing the virtual machine key value on a live system may cause a loss of access to the D3 Virtual Machine.

npibs n

Number of PIBS or ports. This number should be at least equal to the number of users the system is licensed for, plus the expected number of printers (parallel or serial). It is a safe practice to allocate more ports than necessary because it simplifies upgrade procedures when the number of licensed users has to be increased. The only negative side effect for declaring more ports than are actually used is that it takes one frame per port on disk. For example, on a 64-licensed-user system, reserving 128 ports wastes 64 frames on disk, which is negligible. The default is 512.

nphts n

Number of phantom ports expected to be used. There should be at least two phantoms. To determine the number of phantoms required, add one-eighth of the number of licensed users. A minimum of eight phantoms is sufficient for most needs. The default is 64.

hostauthentication on

Host Authentication. Adding this keyword/value pair to the pick0 configuration file enables Host Authentication. If enabled, clients will be logged into D3 using their operating system user-id and password. You can override this option and force D3 to prompt for logon credentials by using the haforcecheck command line option from D3 (see d3 Command for more information).

See the Host Authentication topic in the System Administration Guide for more information on host authentication.

basic shared.mem

Optional parameter that sets aside additional shared memory to contain the shared BASIC code produced by FlashBASIC. The size of this segment should be equal to or greater than the size of all FlashBASIC objects that are expected to be active at one time. That is, it should be large enough to contain all of the FlashBASIC code most commonly used by the application. This amount is some fraction of the total disk space required for FlashBASIC object. Failure to set this parameter sufficiently high can result in extremely poor performance and a large increase in required UNIX swap space. The usage of this segment can be monitored using the TCL command shpstat. If this field is empty, the code produced by the FlashBASIC compiler is not shared. The minimum recommended size for this parameter is 1024 (1 MB), but some FlashBASIC applications may require somewhere between 10240 to 15360 (10-15 MB). If you are upgrading your system from a release without FlashBASIC to a release with FlashBASIC, this parameter may have a value of 0. Be sure to manually update this value before using FlashBASIC on the new release. The default values are:

For AIX:

12.5% of the total memory.

For Linux:

75% of the available memory minus BASIC memory.

brkchr hex.character

Break character redefines a character to simulate a BREAK key for use with devices that do not have a BREAK key, like some graphics terminals. The value is the hexadecimal value of the character. To disable the BREAK key completely, type ff.

For AIX:

Default value is 00, which is the CTRL+@ or BREAK key.

For Linux:

Default value is 0x00, which is the BREAK key.

escchr hex.character

Hexadecimal value of the character defined to push a level. To disable the escape (push level) function, but not the ESC key as a normal character, type ff. The default value is 0x1b, which is the ESC key.

absbase fid

Base FID of the boot ABS. The default is 24. (x18)

WARNING—Changing this value on a live system causes data corruption.

abssize hex.size

Hexadecimal value of the size (in frames) of the boot ABS. The value varies with the release.

WARNING—Changing this value on a live system causes data corruption.

abslock on|off

Lock the ABS into memory. Turning this option off saves about 2 MB in memory, but performance loss is significant, so this option should always be on. This option creates a shared memory segment for the ABS and all processes are attach to it with read-only permissions. This keeps the ABS area from becoming corrupted. To disable this feature, use the absprotect command in this configuration file or use the -b option to the executable on the command line.

For AIX:

Option should always be on since it has (at least) 8 MB of physical memory.

For Linux:

Option should always be on.

ShareTheABS vm.id

(Optional) Virtual machine identifier of the ABS to share.

This configuration option allows multiple virtual machines to share the same copy of the ABS. Since each copy of the ABS can be several megabytes, significant memory savings can be achieved on systems with several virtual machines.

WARNING—It is critical that each virtual machine pointing to a specific ABS be running the exact same version of D3 and be on the same patch level. This option should be commented out, and the virtual machine must be rebooted when you upgrade the ABS in any way. Once all virtual machines are back to the same patch level, this option can be reinstated.

CAUTION—If you are unsure about how and when to use this option, do not use it.
If you only have one D3 virtual machine on your system, ignore this option.

blkfid n

Blocking factor for the frames (frame size) in the UNIX read/write queue.

WARNING—Changing this value on a live system causes data corruption.

bootsleep n

Specifies the number of seconds to wait on autoboot.

flush n

Flush wait period is the number of seconds it takes before the system begins to flush memory back to disk. The smaller the number, the more frequent the flushes take place and the higher the number of disk writes that occur. A value of -1 indicates that the wait period is infinite (flushing is not complete). A value of 10 to 20 seconds should be adequate for most systems. A value of 30 seconds should be considered the maximum. The default value is 10.

flushers

Specifies the number of flusher processes to start for writing memory to disk.

dwqnum queue.size

Defines the size (in bytes) of the internal write queue. Increasing this queue reduces the probability of awakening the flusher on critical demand, thus reducing the number of flushes. The drawback to increasing the write queue size is that the flusher works in bursts, which can overload the disk I/O channel when this phenomenon occurs. The default is 256.

crange beg.port end.port

Use the crange option to specify a range of ports (where beg.port is the beginning port number and end.port is the ending port number) for use by any connections made to D3 via the C interface (the _CP_library). This range includes connections made using the ODBC Server (SQL and ODBC class library connections).

NOTE—It is the system administrator’s responsibility to ensure that no other D3 processes are started in the specified range. D3 does not prevent processes with specified port numbers from starting in a set range. For example, either:

or

would start a D3 process on port 56, if available, even if port 56 is included in a set range.

Ranges do not restrict the number of processes of a specified type to the number of ports included in a range. For example, if you use the command:

ODBC processes would start at 51 and continue using ports up to 100, a total of 50 ports. If the 51st ODBC process was started, it would start at the first available D3 port, starting at port 1.

clocal on|off

Turns on or off the clocal UNIX stty setting. If set to on, hardware handshaking is enabled. If set to off, hardware handshaking is disabled.

serialrange beg.port end.port

Use serialrange to specify a range of ports (where beg.port is the beginning port number and end.port is the ending port number) to be used by floating serial or Telnet connections. These connections are any made to D3 via a UNIX logon, that do not include a D3 port number.

NOTE—It is the system administrator’s responsibility to ensure that no other D3 processes are started in the specified range. D3 does not prevent processes with specified port numbers from starting in a set range. For example, either:

or

would start a D3 process on port 56, if available, even if port 56 is included in a set range.

Ranges do not restrict the number of processes of a specified type to the number of ports included in a range.

rawdisk on|off

Specifies whether update protection is turned on (default)or off.

CAUTION—This feature should only be turned off if the user is fully aware of the consequences of such an action.

onhalt UNIX.command.name

Executes the specified UNIX command or script upon shutdown of the virtual machine.

telnetrange beg.port end.port

Use telnetrange to specify a range of ports (where beg.port is the beginning port number and end.port is the ending port number) to be used by a Telnet turnkey connection that does not specify a D3 port number.

NOTE—It is the system administrator’s responsibility to ensure that no other D3 processes are started in the specified range. D3 does not prevent processes with specified port numbers from starting in a set range. For example, either:

or

would start a D3 process on port 56, if available, even if port 56 is included in a set range.

Ranges do not restrict the number of processes of a specified type to the number of ports included in a range.

user username

Changes the effective user for the D3 Virtual Machine. This is used for changing permissions.

groups groupname ... groupname

Specifies the groups that are allowed access to the D3 Virtual Machine. A user must be a member of one or more groups to have access to the D3 Virtual Machine. This is used for granting or denying access to the D3 Virtual Machine.

disk path offset size

Disk statements define the D3 file system for the virtual machine.

• The path parameter specifies the UNIX file path of the virtual disk.

• The offset parameter specifies the offset in virtual disk (usually 0).

• The size parameter specifies the size of the virtual disk up to 2 terabytes. The specified size must be a multiple of 4. The installation procedure automatically rounds down to a multiple of 4.

For maximum performance, place these divisions on different disk drives and on a different disk than the UNIX swap area (disk striping).

WARNING—Changing the order of the disk statements on a live file system causes data corruption. If you want to increase the file system size by adding disk statements, append the additional disk statements to the end of the list.

The example below illustrates disk statements for disc 0 and disc 1:

tape path block.size type density

Tape statements define the tape devices available for use by the D3 virtual machine. See the Tape_Devices section below for more information.

tape path block.size type density

path

UNIX file path of the tape device. This device must already exist (with any drivers already loaded) for D3 to properly use the device. The device paths illustrated below are examples only; your device paths may be different. Note that these file paths refer to the no rewind devices, which are required for all D3 tape devices. For example, tape /dev/pipein where the device code = c.

NOTE—The underscore character (_) is not allowed in the name of a compressed pseudo-tape device.

block.size

Block size of the device. The block size is set according to these conventions:

• For floppy disks, this is usually 500.

• For half-inch tape devices, this is usually 4096 or 8192.

• For other tape devices, this is usually 16384.

The block size for compressed pseudo tape devices contains the number of 1 KB (1024 byte) blocks to write prior to compression before the file is closed and the tape operation cascades to a new file. If this number is less than 1000, the device does not cascade and may run into UNIX file size limitations.

NOTE—This parameter no longer serves a useful purpose, other than marking a space during parsing of the configuration file, and is required. The exception is the compressed pseudo tape device.

type

Specifies the type of tape (magnetic media) device.

NOTE—Pseudo tape devices do not need to be compressed. For compressed pseudo tape devices, data is written compressed and read uncompressed using gzip utilities (to eliminate the 2 GB file size limitation on compressed tape devices). At user specified limits (before compression), the UNIX file name changes and cascades the pseudo tape device to the new file name. For example, given this tape definition in the pick0 configuration file:

If a data save has more data than the limit specified (10,000 1024 byte blocks, on 10 MB), the device /tmp/pseudo is closed and the save cascades to /tmp/pseudo-1. After the second 10 MB is written, the device /tmp/pseudo-1 is closed and the save cascades to /tmp/pseudo-2. This process continues until the save is finished.

f

Floppy disk or uncompressed pseudo tape

q

Quarter-inch streaming tape

d

4mm digital tape

v

8mm digital tape

h

Half-inch tape

c

No rewind device (pipe)

p

Compressed pseudo tape (cascading)

density

Specifies the read/write density of the device.

Device

Default Density

Low Density

Medium Density

High Density

q

l

ld

.

lh

d

l

.

.

lh

v

l

.

.

lh

h

l

ld

lm

lh

The above device type parameters are ignored by the system and used as a place marker.

c

lx

.

.

.

f (floppy)

lx

ld

.

lh

p, f (pseudo)

lx

.

.

.

NOTE

There are some differences from what a D3 user might expect in the way tape is handled on AIX, due to the way the AIX drivers work.

tape /dev/rfd0h 500 f lq

#3.5 floppy

1.44M high density

tape /dev/rfd01 500 f ld

#3.5 floppy

720K low density

tape /dev/rmt1.1 16384 q lh

#SCT high density

tape /dev/rmt1.5 16384 q ls

#SCT low density

tape /dev/rmt0.1 16384 v l

#8mm tape

tape /home/tmp/floppy 500 f lx

#temporary floppy device

tape /dev/pipein 500 c lx

#data in/out from/to 'some other'

tape /tmp/pseudo 1000000 p lx

#compressed pseudo tape

tape /dev/fd0H1440 500 f lq

#3.5 floppy

1.44M high density

tape /dev/fd0H720 500 f ld

#3.5 floppy

720K low density

tape /dev/nst(x) 16384 q lh

#SCT high density

tape /dev/nst(x) 16384 q ls

#SCT low density

tape /dev/nst(x) 16384 v l

#8mm tape

tape /dev/nst(x) 16384 d 1

#4mm tape

tape /home/tmp/floppy 500 f lx

#temporary floppy device

tape /dev/pipein 500 c lx

#data in/out from/to 'some other'

tape /tmp/pseudo 1000000 p lx

#compressed pseudo tape