prestored.commands Article/Article, tcl.set-imap Verb: Access/TCL, Article/Article, ap.b-trees Article/Article, basic.key Statement/BASIC Program, modulo.def Definition/General, up Introductory/Update Processor, Verb: Access/TCL, tcl.export Verb: Access/DOS, ue.007a User Exit/BASIC Program, Attribute Defining Item/BASIC: Syntax


Command prestored.commands Article/Article
Applicable release versions: AP
Category Article (24)
Description short tutorial on using Update processor prestored commands.

contributed by Terri Hale. Original article ran in PickWorld Magazine.

A "prestore command" defines a series of Update processor (UP) commands and embedded text which can be saved and recalled for later use. Once defined and saved, prestore commands can be used during the current update session or recalled and used in subsequent update sessions.

Prestore commands provide the user with a new programming language and are used to add, delete or modify items in files. Prestores can be performed on data files, against select lists, correspondence, documentation, programming and other text files.

Prestore commands may appear cryptic to anyone except the author of the commands. This is because there is a logic based on a step-by-step definition of each prestore which must be determined before the prestore is written.

There is one active prestore buffer available for each update session. This buffer can be re-used as many times as necessary. Prestore commands can be loaded into the buffer and modified using UP commands. The following table contains a list of UP edit commands.

<ctrl>+e Deletes text from the current cursor position to the end of the command.

<ctrl>+g Positions the cursor at the end of the current command.

<ctrl>+h Backs up the cursor one position and is equivalent to the backspace key on most terminals.

<ctrl>+i Moves the cursor to the next tab position.

<ctrl>+k Positions the cursor right one character.

<ctrl>+l Deletes one character from the current cursor position.

<ctrl>+m Terminates the prestore command.

<ctrl>+o Deletes a word beginning with the current cursor position.

<ctrl>+t Positions the cursor at the beginning of the prestore.

<ctrl>+u Moves the cursor forward one word.

<ctrl>+w Inserts a blank at the current cursor position.

<ctrl>+x Clears the command line.

<ctrl>+y Moves the cursor backward one word.

<ctrl>+zz Will undo the last delete or data change.

The default prestore buffer contains the command "zn", which advances the cursor to the next page. Note: the default buffer contents do not display when editing the prestore buffer.

There is no limit to the number of prestore commands that are available, because prestore commands are saved like all other items in the Pick System. Each prestore command is saved as an item in a file. The items remain in the file until they are deleted or overwritten. "md" is the default file used for saving pre store commands, but any legal file.reference may be used. The following table illustrates valid file.references:

"file.reference" refers to the data section of file dict filename refers to dictionary level of the file.

"dict.filename,data.filename" refers to an alternate data section of file.

",," refers to another md (account).

",filename," refers to the data section of a file in another account.

",dict,filename" refers to the dict section of a file in another account

Prestore commands may contain both UP commands and literal text. When literal text is included as part of the command, the text must be enclosed in single or double quote marks. When UP commands are designated in the prestore command, the UP commands are typed in WITHOUT depressing the control key. The Update processor will interpret anything in the command that is NOT in quote marks as a UP command. Figure B summarizes the UP commands used with to create, save, write and execute prestore commands.


<ctrl>+zl Edit prestore command

<ctrl>+zw{(file.reference}<ctrl>+m Saves prestore command

<ctrl>+zr{(file.reference}<ctrl>+m Loads prestore command or <ctrl>+zr{(file.reference} <ctrl>+p

<ctrl>+p Executes command in buffer.

<ctrl>+p Repeat prestore command.

Editing Prestore Commands

The <ctrl>+zl command is used to create or edit a prestore command in the prestore buffer. After typing in the command <ctrl>+zl, the Update processor displays the following prompt at the top left corner of the terminal screen:


The prestore command is typed in immediately following this prompt. The command is terminated by either <enter> or <return> or <ctrl>+m. The UP command <ctrl>+p is used to execute the prestore command. The example below assumes that the Update processor is in overtype mode.


<ctrl>+zl command to define prestore
P: terminal prompt for command
r'inserting'r<return> actual prestore command

The prestore command above causes the following action:

<ctrl>+r = puts UP in insert mode
'inserting' = literal text
<ctrl>+r = puts UP in overtype mode

Saving Prestore Commands

The <ctrl>+zw command is used to write the contents of the prestore buffer to a file for later use. The command <ctrl>+zw causes the Update processor to prompt with:

Prestore id:

at the top left corner of the terminal screen. At this time an item-id may be specified or a file.reference and item-id may be specified. If only an item-id is entered, the prestore command will be saved in the current master dictionary (md). If the md already has an item with the specified item-id, the following prompt displays at the top left corner of the screen :

'' item exists on file, press "y" to overwrite:

If any key other than "y" is typed, the prestore command is NOT saved. If "y" is typed, the md item that was on file is overwritten with the prestore command. If the response to the prompt for Prestore id is a file.reference and item-id, the command is written to the designated file with the specified item-id. The format of the saved item is :

attribute 1 = p
attribute 2 = prestore command

The following example shows a prestore command composed of only a literal string, with no UP commands. Since there is no file.reference specified in response to the Prestore id prompt, the command will be saved in the md.

u document invoke UP to edit document
<ctrl>+zl command to define prestore
P: terminal prompt
'This is text'<return> actual prestore command
<ctrl>+zw command to save prestore
Prestore id: terminal prompt for item-id
id<return> user-defined item-id

The next example shows a prestore command consisting of UP commands and text. The command is saved in the file commands with the id of 'holdit'.

u document invoke UP to edit document
<ctrl>+zl command to define prestore
P: terminal prompt
mmr'This is text'mr<return> actual prestore command
<ctrl>+zw command to save prestore
Prestore id: terminal prompt for item-id
(commands holdit<return> user-defined file and item-id

The command in the above example does the following :

mm issues two carriage returns
r puts UP in insert mode
'This is text' text
r puts UP in overtype mode

Commands 'holdit' now contains the following :

01 P
02 mmr'This is text'mr

Loading Prestore Commands into Prestore Buffer

The <ctrl>+zr command loads a previously saved prestore command into the prestore buffer and, optionally, executes the prestore command. After the <ctrl>+zr command has been entered, the following prompt appears at the top left corner of the screen:

Prestore id:

The response to this prompt can either be an item-id (if the prestore command is stored in the current master dictionary) or a file.reference and item-id (if the prestore command is stored in a file other than the current master dictionary.) The item-id is followed by either <return> or <ctrl>+p.

When the <ctrl>+zr command is followed by <ctrl>+m, the contents of the prestore command are loaded in the prestore buffer but the command is not executed. When the <ctrl>+zr command is followed by a <ctrl>+p, the command is executed.

Once the prestore buffer has been loaded, it can be executed any time during the current update session using <ctrl>+p.

The following example shows how to load the prestore buffer with a saved prestore command from the current master dictionary without executing the prestore command.

<ctrl>+zr command to load prestore buffer
Prestore id: terminal prompt for item-id
id<return> item-id from md

The next example shows how to load the prestore buffer with a saved prestore command from the file commands using the item-id of 'holdit'. The command is immediately executed using <ctrl>+p.

<ctrl>+zr command to load prestore buffer
Prestore id: terminal prompt for item-id
(commands,holdit<ctrl>+p file.reference,, execute

Executing a Prestore Command

The <ctrl>+p UP command is used to execute the prestore command in the prestore buffer. The default command in the prestore buffer is <ctrl>+zn. Operating in default mode, the UP command <ctrl>+p advances the cursor to the next page. <ctrl>+zl or <ctrl>+zr can be used to change the contents of the prestore buffer.

Repeating Prestore Commands using Saved Lists

If the UP command "p" is the last command in a prestore command, the prestore command will be repeated. When a select list is in effect, the "p" command causes the entire prestore command to be repeated for each item in the list. The example below shows how to create a recursive prestore command which will be used to search and replace text from a list of items.


get-list documents retrieve previously saved list
u document invoke UP on document file
<ctrl>+zl command to define prestore
a'old'r'new'nxfp<return> actual prestore command
<ctrl>+p execute the prestore command

The prestore command used in the example above does the following:


a UP command to search
'old' text to search for
r UP command to replace
'new' text to replace with
n UP command to replace all occurrences
xf UP command to file an item
p UP command to repeat prestore command


Command tcl.set-imap Verb: Access/TCL
Applicable release versions: AP, AP 6.1
Category TCL (746)
Description defines a keyboard input and/or a terminal output translation table, through which any sequence of keyboard input and terminal output characters can be translated into any other sequence of characters.
Input translation can be used to translate special key sequences, like "ESC [ A", into a sequence understandable by the application.
Ouput translation can be used to convert a character into an appropriate escape sequence, for example, to change fonts on a printer, print the character, and change the fonts back.

The translation is based on the notion of 'input sequence', which is a variable-length series of characters which must be received completely within a given time, typically 1/10th of a second, to be recognized as one key stroke, and converted into an output sequence. If an input sequence is not received within the specified time, or if a character received is not part of a valid sequence, the sequence is aborted, and all characters received so far are 'de-sequentialized' and passed to the application or displayed as a series of discrete characters.
When applied to a terminal output translation, there is no notion of timeout, but there are some restrictions (see the section 'Warnings' below).

The translation is described in a table which is associated to each port. See the REF documentation 'keyboards' for the format of the table. A table can be shared among different ports. Each input and output table contains a 'main' translation table and an optional 'alternate' table. The two tables have identical structure and capabilities. The main table is active when the translation is activated. A special input sequence can be defined to switch to the alternate table until it is switched manually back, or for one translation (keystroke) only.

An input sequence can have from one to 127 characters. An output sequence can be from 0 to 127 character long. If an output sequence is null, the corresponding key is made inoperative (input) or the data is not displayed (output).

Without a numeric option, the current port is affected. Optionally, a specific port can be specified by using the port number as a numeric option.

A <BREAK> key aborts any pending sequence and sets the main translation table as the active one.

If there is no argument, the translation mechanism, if currently active, is disabled.

"" The item-id of the translation table, located in the 'keyboards' file in the 'dm' account. The format of the keyboard item is described in the REF documentation 'keyboards'. If the item has already been compiled into a translation table and stored as a binary item in the dictionary of the file, the translation item is not re-compiled, unless the "c" option is used.

"time.out" Value of the time out, expressed in milliseconds, after which an incomplete input sequence is aborted. If not specified, the value defined in the item "" by the 'timeout value' modifier in attribute one, is used. If none is specified, the default value is 100 milliseconds. The "time.out" should be adjusted to the baud rate and possible special conditions, like network delays, to detect sequences of characters properly. If "time.out" is 0, the translation mechanism will wait indefinitely between characters of a sequence until either a valid sequence is received or until an unexpected character 'breaks' a sequence. The timeout does not apply to output translation. See the section "warning" below for information about adjusting the timeout value.

If the one-to-one input/output translation defined by the TCL command 'set-iomap' is also active on this port, the translation defined by 'set-imap' is processed first, and each character of the resulting string is passed through the one-to-one conversion table set by 'set-iomap'.

When used on PC-based AP/SCO or AP/Native, the keyboard setting defined by 'set-kbrd' is processed first.

set-imap can be called automatically by the TCL command TERM with the (K) option, if the item defining the terminal has the name of a keyboard translation item in the value 4 of attribute 1.
Syntax set-imap { {time.out}} {(options}
Options port.number Port number in decimal. If not specified, the current port is used.

c Compiles the item. This option must be used when "" is modified. "" is compiled into a binary item and stored in the dictionary of the "keyboards" file.

v "verbose". Displays information about the translation table (name, size) and the modifiers used in attribute one.
set-imap ibm3151
  Sets the keyboard translation to an ibm3151.

set-imap wy-50 100 (24
  Sets the keyboard translation to a wy-50, changing the timeout to 100 ms, on 
port 24.

set-imap att605 (c
  Sets the keyboard translation to an att605, recompiling the item first.

  Disables the keyboard input translation.
Related tcl.set-iomap

Command Article/Article
Applicable release versions: AP
Category Article (24)
Description discusses system security.

Contributed by Chris Alvarez. Original Article ran in PickWorld Magazine.

This article assumes a working knowledge of the system file structure and design.

One common misconception about the Pick System is that system security does not exist. While the security features available in Pick are not as extensive as those available in most Unix releases, it is possible for a System Administrator to configure a security system that is effective for most installations. Unlike R83, Advanced Pick employs the concept of a USERS file. This file contains a description for each user permitted to logon to the system and enables the System Administrator to control the system at both the user and account levels. A separate user item should be added to the USERS file for each authorized user of the machine. For assistance in creating entries into the user file, please reference page 313 of the Advanced Pick Reference Manual or consult Technical Bulletin #T28. The file contains several attributes of interest to this discussion including the KEYS, PASSWORD, OPTIONS and PRIVILEGE attributes.

The password for the user is probably the most important part of the security system because most of the security measures available are based upon the information found in the USERS file. Each user should be issued a password and those passwords should be changed on a regular basis. Care should always be taken to ensure that a user's password is not shared with other users. It is possible to multi-value the password attribute to facilitate multiple passwords for one user. While this is not recommended for the user, it is useful when used on the account to allow a master password for the System Administrator. Make sure each user in the USERS file is assigned a password, including those received with the original release. For exam ple, the user '?' was shipped on some earlier releases of Advanced Pick as a way of entering new users but provided a 'backdoor' into any secured system.

Each account found on the system should also be assigned a password, including the system accounts shipped with the original product. This list should include any entries in the "mds" file that are q-pointers to other accounts. Multiple passwords may be assigned to any account to facilitate the ability to create several password layers.

This is accomplished by multi-valuing the password attribute in the account item found in the "mds" file.

The next step in securing the system is to limit what areas the user is allowed to access. This is done in three ways. First, the administrator can limit the system resources available to the user through the use of system privileges secondly, the administrator can limit access to TCL and thirdly, the administrator can limit which files the user is able to use through the use of update and retrieval locks.

System privileges can be set to one of three levels ranging from SYS0 to SYS2, with SYS2 as the highest level. In most installations it is a common practice to set the privilege level for each user to the highest setting because of a lack of understanding of the feature. Only those users that help in the administration of a system should be assigned SYS2 privileges, while most users should be assigned SYS1 privileges. Unfortunately, the exact list of features available to each system privilege level is not available. (ed. note: see "system privileges" for a complete list.) What is known is that SYS0 privileges exclude usage of all peripheral devices and system functions. This includes the use of the TCL verbs CLEAR-FILE, DELETE-FILE and CREATE-FILE. Users with SYS1 privileges will be able to access peripheral devices and some system functions. The biggest reason for setting the majority of users to either SYS0 or SYS1 privilege level is that neither has full access to the system debugger.

A user can easily be denied from using TCL by placing the character 'r' in the options attribute, which is attribute 9, of their item in the users file. In this manner, the administrator can limit the number of users with access to TCL commands. When a user with this restriction tries to get to TCL either through level pushing or the use of the break key, the user will be returned to the original logon program for the current account.

The file-defining item (d-pointer) of a file contains two fields for lock codes to limit a user's access to a file unless the user item contains matching codes. Although these facilitates exist in R83, they have been enhanced in Advanced Pick to include multi-value codes.

There are two types of locks, update and retrieval. When an update lock is placed on a file, only those users with matching lock codes in their user item will be allowed to make updates to the file, but any user will be able to view the items in the file. Conversely, the retrieval lock limits the viewing of items in the file. The lock codes can be any character string, but it is suggested to limit them to something simple, such as the name of the file.

For example, if the System Administrator wanted to limit the access to the customer file, the word 'customer' could be placed as the update lock on the file-defining item for the customer file. Only those users with the word 'customer' found in the list of keys on their user item would be allowed to update the file. Using this system, the administrator would place the name of the file on the file-defining item for each file needing protection. The KEYS attribute of each user item in the user file should be multi-valued with each file name the user is allowed to access.

One last step can be taken to track the updates of a sensitive file. It is possible to call a FlashBASIC or Pick/BASIC program anytime something is changed in a file, regardless of the process used to make the change. This includes updates from tape, FlashBASIC or Pick/BASIC and any editor. Place a CALLX on attribute 8 of the file-defining item for the data section of the file using the following syntax:


Where PROGRAM is any cataloged FlashBASIC or Pick/BASIC subroutine with one argument passed to the subroutine. The following subroutine is an example of an audit program to keep track of which user changes a file.

A caution about using this or any auditing program: Pick Systems receives numerous calls each week from customer's complaining their machine has ground to a standstill over the past months. The support department usually discovers that the customer's application contains a program that writes auditing or history information to a history file. When the application was installed, the file is usually sized at well below the needed level and becomes incredibly fragmented over time. The fragmentation will slow the system down and can only be remedied by using a file resizing program against the data base, followed by a full system restore. The subroutine below will create a data level file called AUDIT with a default modulo of 3. If the file being audited receives numerous transactions, please change the modulo as necessary.

001 subroutine audit(new.item)
002 * Subroutine to create an audit trail for any file.
003 * 16 October 1991 CJA
004 *
005 * To use:
006 *
007 * This program can be used to keep a complete audit trail of
008 * changes made to any data or dictionary section of any file.
009 * On any file d-pointer, a CALLX calls this program at file
010 * time using the following syntax as the correlative:
011 *
013 *
014 * To audit the dictionary section of a file, place the
015 * CALLX on the d-pointer for the file found in the master
016 * dictionary. For the data section, place the CALLX syntax
017 * on the d-pointer for the data section in the dictionary
018 * of the file.
019 *
020 * When an item is filed into the file, an audit record will be
021 * written to a data file called AUDIT. If this file does not
022 * exist, the program creates the file. The audit record will
023 * include only lines which have been changed and are stored
024 * in the following format:
025 *
028 * .
029 * .
030 * .
032 *
033 * The item-id includes the original item's item-id
034 * concatenated with the user id and the timedate the item was
035 * changed and looks as follows:
036 *
037 * item-id*user*timedate
038 *
039 * The audit file is created with a default modulo
040 * of 3. Depending on activity in the file, this audit
041 * file could become badly sized and cause speed degradation.
042 *
043 equate am to char(254)
044 equate vm to char(253)
045 *
046 * Open file and retrieve old.item for comparison to new.item.
047 *
048 = access(11)
049 = access(10)
050 open to f.file
051 read old.item from f.file, else old.item = ''
052 *
053 * Verify existence of audit data level file by creating file
054 *
055 execute 'create-file data '',audit 3' capturing trash
056 *
057 * Find the differences between the old.item and the new.item and build
058 * audit record. If no differences exist then do not build audit record.
059 *
060 audit.record = ''
061 no.lines = dcount(old.item,am)
062 for line = 1 to no.lines
063 if old.item<line> # new.item<line> then
064 audit.record<-1> = line:vm:old.item<line>:vm:new.item<line>
065 end
066 next line
067 *
068 * Write audit record if item has changed.
069 *
070 if audit.record # '' then
071 user = field(oconv('','u50bb'),' ',2)
072 ='*':user:'*':time():date()
073 open',audit' to f.audit
074 write audit.record on f.audit,
075 end
076 return


Command ap.b-trees Article/Article
Applicable release versions: AP
Category Article (24)
Description discusses using Advanced Pick B-Trees and other advantages of Advanced Pick.

Contributed by Terri Hale
(original article ran in PickWorld Magazine)

In my travels over the past couple years spreading the gospel of Advanced Pick (AP) to Pick user groups and students in training seminars, I've been asked "What would I gain by switching to AP?"

There are many features which warrant the upgrade. I particularly like the Update processor for data entry and retrieval. Another feature which I've become increasingly dependent on is the tcl-stack. Level pushing is a feature which I'd rather not live without. Unlimited item size is great. Furthermore, prototyping application software can be done in a few hours or less using UP and all the new processing codes.

But, this article will focus on one feature which I feel justifies the upgrade (or new installation) above all others. This single feature is AP's implementation of indexes or B-Trees. Let me explain the merits and clarify some common mis conceptions regarding this feature.

Index Maintenance & Housekeeping

AP's indexes need to be created once and only once using the create-index verb. The syntax for this TCL statement is:

create-index filename a.code

Any (or) all attributes in a file can have an index created. But, not all data fields lend themselves to indexing. The only limitation to the number of indexes that can be created is disk consumption.

The size of the index consists of the length of the header, key, and item-id, the number of nodes and the number of items in the file. To find the number of frames used in an existing index, the verb nframe-index is available. The syntax for this TCL command is:

nframe-index filename a.code

An "*" can be substituted for the a.code to find the size of every index on a file.

Once the index has been created, the system AUTOMATICALLY updates the index each time the file is updated. This includes updates which occur when loading items into a file (with the t-load verb), deleting items from Pick/BASIC or UP and copying items into a file (using the copy verb).

If you suspect a corruption in an index, you can validate its integrity using the verify-index verb. The syntax for this verb is:

verify-index filename a.code

If there is a problem with the index, you can delete it and then recreate it. The syntax for deleting the index is: delete-index filename a.code

Saving Indexes

You CAN save the indexes on a file-save. In initial releases of AP there was no option to save the indexes. But in the current releases, the indexes can be save by using the "B" option on a file-save. Now you can either save the indexes or regenerate them after a restore. Dealer's choice.

Pick/BASIC and Indexes

You CAN access the indexes from Pick/BASIC as well as from the Update processor. Think about the impact of using the indexes from Pick/BASIC for a moment. For your existing applications written in Pick/BASIC, you could tie into the AP indexes and experience immediate update and retrieval of data. No more cross reference files or inverted lists to be periodically regenerated.

Access and Indexes

On the retrieval side of things, the verbs sselect, sort and list utilize the index if there is an index corresponding to the sort key. For example, consider an index on the field in an orders file. I executed the following statement:

sort orders by

on my Compaq portable 286. This report took 3 seconds to begin output (in a file of 411 items). When I removed the index and executed the same command, output began after 10 seconds.

Using B-Trees from the Update Processor

Let's build a dictionary item in the orders file called to demonstrate how to use indexes with the Update processor. This dictionary will allow us to look up values (names) in the customer file and also allow us to search through our orders file for specific customer orders.

The first step to using indexes is the creation of the index. For our example we would need an index on attribute 1 of the orders file.

create-index orders a1

Since we are also going to access a remote index in the customer file, we also must have an index created on customer attribute 1.

create-index customer a1

When using B-Trees with the Update processor, you MUST define an index correlative on the input-conversion attribute of the dictionary. There may be one (local or remote) or two (one local and one remote) index defined in the dictionary.

See the following table for the dictionary item called in the orders file.

DICT orders ''


dictionary-code a
attribute-count 1
substitute-header name
output-conversion tcustomer.file;x;;1
attribute-type l
column-width 10
input-conversion i

"i" is a "local" index on the name attribute and is used to locate existing orders for this customer. To use, type in

"string" control<f> = forward search control<d>=backward search

"icustomer;a1" is a remote index on customer(name). Used to locate valid customers. To use, type in

"string" control<u>=forward search control<y>=backward search

macro name address zip

Default input attributes used when zooming to the customer file.


To get into the orders file we will use the UP command:

u orders

orders NEW ITEM _

At the prompt, the user can enter a partial name and then either search the customer file (<ctrl>+u, <ctrl>+y) for customers whose name begins with the string entered or search the orders file (<ctrl>+f, <ctrl>+d) for exist ing orders whose begins with string entered. Results are immediate. No waiting.

Using B-Trees from Pick/BASIC

As mentioned above, the index must have been created prior to accessing the index from either Pick/BASIC or UP. If we haven't already created the index we would do so as follows:

create-index orders a1

The Key and Root (see below) are two new statements in Pick/BASIC which allow the programmer to access indexes.

root filename,a.code to root.variable {then..else statements}

When the create-index verb is executed, the system puts the root frame address in the file-defining item on the correlative attribute. The root statement grabs this address (root.variable). This root.variable is used by the subse quent key statement. The a.code must be in the same format as the create-index verb.

key('operator',root.variable,index.key, {then..else statements}

The key statement must be preceded by the root statement. The components are defined as:

operator description

'c' Will return an index.key on an exact match or the next higher index.key and item-id. Normally this operator is used first to get the initial item and then another key statement using the 'n' operator is used to get the NEXT item.

'n' Will return an index.key on an exact match or the next higher index.key and item-id. This is generally used in a loop construct when searching for all items that match the search criteria.

'p' Will return an index.key and item-id on the previous item. Similar to 'n' but the search is backwards. This is also helpful to use in a loop construct to get the last 'n' number of items.

'r' Will only return an index.key on an exact match.

'v' Used to verify the index if a corruption is suspected. It will locate a given index.key and item-id and verify that the pre-defined item-id equals the item-id returned.

root.variable This variable contains the address of the index obtained by the previous root statement.

index.key This variable contains the string being searched for. It must be pre-defined before using the key statement. If the string is found, the results are returned into this variable when using the 'c', 'n' or 'p' operators.

item-id This variable will be assigned the item-id of the item that contains the index.key. The item-id MAY be preassigned when using the 'p' or 'n' operators. It MUST be preassigned when using the 'v' operator.

"then..." Is executed if the item-id is found or if the index.key verifies with the 'v' operator.

"else..." Is executed if the item-id is not found or if the index.key does not verify with the 'v' operator.

The following Pick/BASIC program will search the customer file for all people whose name begins with 'terri'. It will then print the customer's name and phone number:

* Program to find and print all names
* beginning with 'terri'
file customer
root 'customer','a1' to customer.root else
stop 'Index not available'
end = 'terri'
key ('c',customer.root,,id) then
loop while[1,5] = do
read customer from id then
crt "customer= ":customer(name):' ':customer(phone)

Running this program on my customer file yielded three items in one second. Compare this to using the following Access statement:

list customer with name = "terri]"

The speed of retrieval using indexes in Pick/BASIC is most impressive when accessing very large data files. Output occurs instantaneously regardless of the size of the file.

Whether the reader has already installed Advanced Pick or is contemplating purchasing the product, I encourage you to investigate the benefits to your organization of utilizing AP B-Trees.


Command basic.key Statement/BASIC Program
Applicable release versions: AP, AP 6.2, AP 6.1
Category BASIC Program (486)
Description provides the ability to sequentially "cruise" on any defined b-tree index for an item-id.

The "root" statement must precede the "key" statement.

The "operator" indicates the type of index search to use, and may be one of the following choices:

c Compares, left-to-right, against the "index.key" and returns the first item-id whose index matches into "". If no match is found, the next sequentially higher index and first associated "" are returned.

l Returns the last partial key. If a non-null "" is passed, then this operation is identical to the "p" operator. However, if a null "" is passed, then this function returns the highest valued key in the index which still matches the passed key. This feature is only available in releases 6.1.0 and greater.

n Returns the next "index.key" and "". If more than one "" exists for an "index.key", this returns the next "". After all "item.ids" for an "index.key" have been returned, or if the "" is null, it returns the next "index.key" and "".

p Returns the previous "index.key" and "". If more than one "" exists for an index.key, this returns the previous "". After the first "" for an "index.key" has been returned, or if "" is null, it returns the previous "index.key" and the last "".

r Returns the "index.key" and "" only on an exact match with the "index.key".

v Verifies the index. Locates the given "index.key" and "" and verifies that an exact match can be found.

x Works like the "n" option, but returns ALL item-id's matching the given key as a dynamic array. If the passed item-id is null, then the data for the passed key is returned. If the passed item-id is non-null, then the list for the NEXT key is returned. The vc.expression, if present, returns the number of elements found with an original value position not equal to 1. If vc.expression is non-zero, then the item-id list may contain duplicate item-id's. Available in releases of AP 6.2 and higher.

root.variable is the b-tree root fid associated with the target index. It must be initialized by the "root" statement, and must be defined prior to using the "key" statement.

index.key specifies a mandatory variable containing the search string. The variable must be defined before using the "key" statement. The actual string found is returned into the variable when using the "c", "n" or "p" operators. The "r" and "v" operators expect an exact match. is the variable that is assigned the item-id of the item that contains the key. The "" need not be preassigned when using the "p" or "n" operators, but must be preassigned when using the "v" operator.

vc.expression is the value number of the key attribute containing the "index.key", returned to the "vc.expression" by the "key" statement. This only works with the 'c', 'n', 'p' and 'r' operators.

The "then" clause is executed if the item-id is found or if the "index.key" verifies with the "v" operator.

The "else" clause is executed if the item-id is not found or if the "index.key" does not verify with the "v" operator.

See the "then/else construct" for an explanation on the use of "then" and "else" clauses in statements that allow or require them.
Syntax key('operator', root.variable , index.key, {, vc.expression} ) {then | else statement.block}
employee.index ='a5'; * phone number attribute
execute "create-index employee ":employee.index
root 'employee',employee.index to e.root else
  print "the index ":employee.index:" not found"
print "Enter phone number to match ":
input e.key
key('n',e.root,e.key, then print

In the "root" statement, "employee" is the file that 
contains the pre-defined index. If the index is found, the root fid is assigned 
to the variable "e.root".

In the "key" statement, 'n' indicates that the 
"next" matching string is to be located. "e.key" is the 
variable which contains the search string and "" is the 
variable to which the actual item-id will be assigned, if it is found.
Related basic.then/else.construct


Command modulo.def Definition/General
Applicable release versions: AP, R83
Category General (155)
Description designates the number of groups (measured in frames) in the primary file space, as indicated during the creation or reallocation of the file.

The modulo is always an integer remainder in the range 0 to modulo-1. The formula to determine the frame number of the initial frame of the group where the item is located is: fid=base+( This initial frame number is commonly called the "base fid".

The modulo of a file is a critical component of the "hashing" algorithm access method. It should never be altered in any file-defining item, as this can cause such problems as gfe's to appear.

During the full or account-restore processes, files are resized according to the optional modulo found in the "reallocation" attribute (attribute 13) of the file-defining item. After changing to the new modulo, all items must be re-hashed before they are replaced. This can cause restore processes (also t-load and copy) to run considerably slower.
Related hashing


Command up Introductory/Update Processor
Applicable release versions:
Category Update Processor (113)
Description UP is a dictionary-driven, full-screen editor and data processor. Used with the Output processor (OP), it operates as a document processor.
UP can be used to view, create, and manipulate file items. UP facilitates editing of text, dictionaries and programs, as well as data files (remember, everything in Pick is an item in a file). When used as a data processor, attribute-defining items in the file’s dictionary are employed to verify and translate data as it is entered and retrieved.
Pick/BASIC subroutines can be called from dictionaries allowing absolute control of all data entry using the Update processor and dictionaries. Without any attribute-defining items specified, UP functions as a full-screen editor.
When invoked, UP copies the specified item to a workspace and displays as much of the item on the screen as it can. UP places the cursor at the upper left corner of the item (top) on the first character of the first value of the first attribute and waits for your input.
Once the item has been loaded, any character you type will overwrite whatever is on the screen. Control keys are used to perform editing functions, but as long as the control key is not down, all characters are entered as typed. An automatic word-wrap feature moves whole words to the next line as they are typed when you overrun the end of the current line. An optional spelling checker beeps and rejects your input when you type a character that does not lead to a legal word.
Text is normally entered in the insert mode (<Ctrl>+r is used to toggle between the insert and overtype mode). While in the input mode, the return/enter key (<Ctrl>+m) creates a new attribute/paragraph. When in the overtype mode, that same key does not create a new attribute but instead goes to the next attribute. The default mode is overtype.
UP commands begin with a control character formed by simultaneously pressing the <Ctrl> key and one of the alpha keys. Some UP commands require more command characters, while others require text input.
Until the item is saved, changes made using UP have no effect on the actual item in the file -- only UP workspace is changed. The item can be exited at any time without filing, by typing <Ctrl>+xe>, and the item in the file will not change.

Using UP as a Text Editor
In the absence of any attribute list, UP functions as a text editor. An attribute list generates a data entry screen with whatever audits and transformations are defined in the corresponding dictionary. The text edit form is to specify just the file name and item list (no attribute list) and if no macro is present on the file-defining item, the raw item will be presented. Refer to the entries update, up, and u for more niformation about the update commands.
update file.reference {item.list} { (options) }

Cursor Movement
The cursor is the underline or block which moves around the screen when characters are typed. Cursors can have various forms depending on the terminal: highlighted, blinking, reverse video, etc. In all cases, the cursor indicates where the next character typed is displayed on the screen.
Cursor movement commands are used to position the cursor anywhere in the item without altering the text. The cursor actually moves on the CRT screen. And, since the screen is only a window into the item, the cursor may be moved off the screen forcing a screen redisplay (scrolling).
<Ctrl> +

k Moves the cursor forward (right) one character.
j Moves the cursor back (left) one character.
n Moves the cursor down one line.
b Moves the cursor up one line.
i Moves the cursor forward to the next tab stop in the line.
u Moves the cursor forward (right) one word.
y Moves the cursor back (left) one word.
f Moves the cursor forward to the next sentence.
d Moves the cursor back to the beginning of the sentence.
g Moves the cursor to the end of the current paragraph.
m Moves the cursor to the beginning of the next paragraph(attribute) if in overtype mode. Creates a new attribute if in insert mode.
t Moves the cursor to the top of the current item.
z n Moves the cursor to the top of the next screen.
z y Moves the cursor to the top of the previous screen.
z h Moves the cursor to the first line of the next screen, then moves the display up 12 lines.
z q Moves the cursor to the first line of the next screen, then moves display up one quarter of a screen.
z e Move the cursor to the end of the current item.
z a Redisplay the screen with the current line at the top of the screen.
z b Redisplays the screen with the current line at the bottom of the screen.
z p Redisplays the screen.
z numeric Goes to the specified line number.

Overtype and Insert Modes
When UP is first entered, it is in overtype mode. This means that characters typed overwrite the characters on the screen. Insert mode is used to insert new text just in front of the text beginning at the cursor. When text is entered in the insert mode, the following text is "opened" and shown on the next line until insert mode is exited or a cursor movement command is typed.
The letter "O" is displayed at the top right corner of the screen when in overtype mode; the letter "I" is displayed when in insert mode. As text is entered in either mode, UP word-wraps the text as necessary. That is, if a character string is longer than the remaining space on the current line, the entire string is moved to the next line. This means you can type continuously within a paragraph (attribute) without pressing the <Ctrl>+m.
<Ctrl>+r Toggle between overtype and insert modes.

To create a new paragraph in the middle of existing text, enter the insert mode and type <Ctrl>+m. This terminates the current paragraph and prompts with the next attribute number. If the cursor is at the end of an item, <Ctrl>+m creates a new paragraph whether or not in input mode. In the absence of a dictionary definition, this is how UP is used as a word processor; each attribute is a paragraph.
<Ctrl>+m Same as <Return>. Always moves the cursor to the beginning of the next attribute. If in insert mode or at the end of an item, <Ctrl>+m creates a new paragraph. If UP is being controlled by a dictionary, <Ctrl>+m does not create a new attribute mark, rather the cursor moves to the next attribute.

Inputting Text Using the Spelling Checker
UP uses a spelling checker to verify text as it is entered. The spelling checker looks at each character to see if those typed so far make a legal word or may become a legal word. The words used by the spelling checker are kept in the words file in the dm account.
In order to activate the spelling checker, a q-pointer must be present on the current account and an index must be generated on attribute 0 of the words file. If an error is detected, the terminal beeps and does not display the last character typed. If an incorrect letter is typed, type the correct one and continue entering data.
To view the words immediately adjacent to the misspelled word in the words file, use <Ctrl>+u to get the next legal word or <Ctrl>+y to get the previous word. Otherwise, press one of the following:
<Ctrl> +
a Override spell checker and accept the characters.
a a Insert the word into the words file and continue.
a a a Turn off spelling checker.
z s Toggle the spelling checker on and off from any point in the item. If the spelling checker is on, <Ctrl>+zs toggles it off; if the spelling checker is off, <Ctrl>+zs toggles it on.

Deleting and Undeleting Text
As text is deleted, the remaining characters in the paragraph are moved to the left. The Cut and Paste commands also delete text.
<Ctrl >+
l Deletes the character under the cursor and moves the text left.
o Deletes characters from the cursor position to the end of the word including the character under the cursor.
e Deletes from the character under the cursor to the end of the sentence.
z o Deletes the characters from the cursor to the end of the paragraph (attribute).
z d Deletes the characters from the cursor to the end of the item.
z z Undo the last delete or data change if the change was made by using one of the control delete keys.

Exiting Items
The <Ctrl>+x commands offer different methods for exiting an item. <Ctrl>+x signals to exit this item and perform one of a series of options. For example, an item can be exited and the information filed (saved), or the item can be exited without the information being filed.
If an item is exited without being filed, the changes made during the editing session are not saved. To save the changes, the item must be filed. Several of the options that exit an item do not file it. If changes have been made to an item during the current editing session and an option is selected that exits the item without filing it, the system double-checks with the user to make sure that the changed information is not to be saved.
All UP exit commands are made up of a minimum of two characters. When the <Ctrl>+x is pressed, the current size of the item, file name, and item-id are displayed on the top line of the CRT. UP waits for an additional command.
b Exits the item and goes back to the previous item in the item list. If there is no previous item, the terminal beeps and remains in the current item.
c Files the current item then compiles and catalogs it. This option is used with Pick/BASIC programs.
e Exits the item without filing it.
f Files the item, then exit it.
i {(file.reference}{}
Renames and files the new item. This command prompts for a standard file item specification where the item is copied. After the file item specification is entered, the system asks if the old item from which the new item was created, is to be deleted. Enter <Ctrl>+y to remove the old item; otherwise, the item is unchanged.
k Exits the item and returns to calling process. If editing with a select list, the select list is terminated.
n Exits current item and creates a new null item. If a name is not entered when the new item is filed, it can be named using the <Ctrl>+xi> command. If there is no id processing code, UP uses the current date concatenated with a system-wide sequence number as the item-id.
o Exits and deletes the item.
p Files the item and prints it using the Output processor (OP).
r Files the item, then compiles and runs it if compilation was successful.
s Files (save) the item and remains in UP with the current item.
x Exits the item without filing it.

Searching and Replacing Text
The search commands in UP offer the capability to search for text, search for text and replace the text, and search for text and, once the text is found, determine whether or not to replace it.
<Ctrl >+
a string <Ctrl>+m
Search for the first occurrence of the specified string. If a match is found, the cursor is displayed on the first character of the matched string; otherwise, the cursor remains at the current location. When <Ctrl>+a is pressed, UP prompts for the search string at the top of the screen.
The search string is not case sensitive. To search for letters that are case specific, enclose the string in single- or double-quotation marks. If the string itself contains quotation marks, enclose those quotes in quotes.
a Search again for the string specified by the last search command. If a search string is not specified, the terminal beeps and displays a message.
a string1 <Ctrl>+r string2 <Ctrl>+n
Search for and replace every occurrence of string1 with the string2 from the current cursor position to the end of the item. When <Ctrl>+r is pressed, UP prompts for the replacing string. After entering the new text press <Ctrl>+n to indicate all occurrences.
The text is replaced as entered. If the replacement is at the beginning of a sentence, the initial letter is replaced as an upper-case letter. To specify an exact replacement of upper- and lower-case letters, enclose the text in single or double quotation marks.
a string1 <Ctrl>+r string2 <Ctrl>+m
Search for the first occurrence of string1. If a match is found, the cursor is positioned on the first character of the match and UP waits for one of the following commands:
Ctrl +
a Do not replace string1. Search again for next occurrence.
n Replace string1 with string2. Replace all further matches.
r Replace string1 with string2. Search again for string1.
x Stop search. Return to edit mode.

Cutting and Pasting Text
Cut commands are used to move or copy data from one place in an item to another place in an item. Text can be cut and deleted or cut with the original left in place (copied). After the text is cut, it is placed in the cut buffer replacing the previous contents of the cut buffer. The cut text in the cut buffer can be pasted in the current document or it can be pasted in a specified item in a file. Text can also be pasted from a specified item and file.
<Ctrl >+
c d Mark the beginning location of the text to be cut and deleted.
c l Mark the beginning of text to cut and leave (i.e., does not remove the cut from the current location in the text and makes a copy for the cut buffer).
c c Mark end of text to cut or copy from the beginning cut and puts the text in the cut buffer.
c p Paste contents of cut buffer at current cursor position. Once text has been put in the cut buffer it remains there for the duration of the current update session in the UP workspace.
c r {(file.reference} {n{-m}} <Ctrl>+m
Read contents of specified item and paste at current cursor location. The optional n parameter is an integer that specifies the first attribute to copy; the optional m parameter is an integer that specifies the last attribute to copy. If a range is not specified, all attributes from beginning to the end of the item are copied.
c w {(file.reference } <Ctrl>+m
Write the contents of the current item cut buffer to the item specified by

Prestore Commands
Prestore commands are used to store and execute a sequence of UP commands. These commands can be used during the current update session or saved as an item in a file and recalled for use in subsequent update sessions. Prestore commands can contain both UP commands and text. To specify a UP command, enter the letter portion of the editing command without pressing the <Ctrl> key. To specify text, enter the text enclosed within single/double quotation marks.
Prestores can be created in the prestore buffer or they can be created as an item in a file. Prestore items can exist in any file and must have a p in the first attribute. The following attribute values will contain prestore commands and text.
<Ctrl > +
p Execute the current command in the prestore buffer. If the prestore buffer is empty, displays the next screen of the item being edited (default).
z l Create or edit a prestore command in the prestore buffer. Most UP commands are available to input and edit the prestore buffer.
z r {(file.reference} <Ctrl>+m
Load specified item into the prestore buffer but do not execute it. The first attribute must be the character p.
z r {(file.reference} <Ctrl>+p
Load the specified item into the prestore buffer and execute it. The first attribute in the item must be a p. The default file is the master dictionary.
z w {(file.reference} <Ctrl>+m
Write the prestore buffer into the specified item. The character p is written as the first attribute of the item. The default file is the master dictionary.

Using UP as a Data Processor
update file.reference attribute.list (options
When UP is called with an attribute list it functions as a data processor. Each attribute name in the UP statement becomes a data entry location on the screen identified by the named attribute. The attribute names are listed along the left of the screen in half-intensity. Dependent attribute names are displayed horizontally across the screen with the controlling attribute. Each attribute-defining item creates a cell on the screen through which data may be accessed and modified under the control of dictionary processing codes. Since a Pick/BASIC program may be called using a processing code, complete application flexibility is provided.
The cursor can be moved, using the previously defined cursor movement commands, from attribute name to attribute name. (Some of the commands function in a different manner. These are defined below.) Data entered or changed next to an attribute name is filed in that attribute when the edited item is saved.
Stored data is subject to output conversions defined in attribute-defining items in the file dictionary prior to display. Data entered using UP is subject to input conversions defined prior to storage on disk. By invoking a single UP command, an entire data access and update screen can be defined. When that command is saved as a macro, it can be recalled any time for file access.UP can be used to scan data using file indexes. When attributes are indexed using the create-index verb, UP can be used to cruise on the index.
The key to cruising is understanding the Balanced Tree (b-tree) indexing feature of Advanced Pick. A b-tree is a structure used to keep an ordered list, such as names, and provides the ability to search through the list very quickly with a minimal number of disk I/Os. Any attribute in a file can contain an index. Indexes are defined using a-correlatives. Once the b-tree has been defined, the system automatically maintains the index.
b-trees allow access to data in ways not before possible. The new access capabilities are cruising (using the file index), cruising (using the file related index), zooming, and double clutching.
Cruising using the file index (local file) is the ability to move from item to item in the current file. You can move forward (with <Ctrl>+f or backward (with <Ctrl>+d through the items on any indexed attribute.
Cruising using the related file index (remote file) provides the ability to view valid data from another file. For example, a sales order file could have an attribute called name which points to the entity file. From the orders file one could view the valid names in the entity file and select the one desired.
Double-clutching means the combined abilities of searching the remote file for valid values and also searching the local file for specific items. For example, in an order file the name attribute could have an index pointing to the entity file allowing for searching of valid people. A local index on the name attribute would allow for searching for all of the orders already on file for that person.
Zooming refers to moving through a defined door to another file. Once in the other file, the user has the option to cruise from item to item in the new file, return to the original file or zoom through a door into yet another file. <Ctrl>+g is the command to zoom to another file.
When the cursor is positioned in a cell belonging to an indexed attribute, the commands <Ctrl>+d and <Ctrl>+f can be used to display the data associated with the item containing an adjacent value in the indexed attribute. The command <Ctrl>+f causes the data associated with the next value in the index to be displayed. The command <Ctrl>+d causes the data associated with the previous value in the index to be displayed.
For example, if an item containing customer name and order number indexed attributes is being displayed on the screen and the cursor is at the order number prompt, the <Ctrl>+f command will display the data associated with the next order number in the order number index. If the cursor is residing adjacent to customer name, <Ctrl>+f causes the data associated with the next customer name in the index to be displayed and customer name is the key. All of the data in the new item associated with the attribute names displayed on the screen is displayed.
When the input conversion attribute in an attribute-defining item specifies an index pointing to another file, that file can be accessed (zoomed to) by using the <Ctrl>+g command. This command pushes the current process one level and accesses the item-id in the pointed to file that matches the current value in the cell where the cursor resides. Attributes to be displayed with that item-id must be specified in attribute 15 of the original attribute-defining item. Several logical views may be defined as macros in Attribute 15 of the d-pointer.
A FlashBASIC or Pick/BASIC program may be called to specify the actual logical view to use for the current data item. It does this by assigning the logical view number into the pseudo-variable "Access (18)." If no attributes are specified, the entire item is displayed. After viewing the new item the original item can be returned to the screen by a file exit command such as <Ctrl>+xe>.
When the input conversion attribute in an attribute-defining item specifies a second index as well as one pointing to another file, the commands <Ctrl>+u and <Ctrl>+y allow the user to cruise on indexes in the pointed to file. The attribute pointed to in the second file must have been previously indexed by the create-index verb. <Ctrl>+u shows the next attribute value in the pointed to file. Only this value is updated and it is shown in the cell where the cursor is residing. What is displayed is subject to the conversions specified in the dictionary of the first file. The command <Ctrl>+y shows the preceding item-id in the pointed to file. In order for UP to function in this manner, the attribute-defining items must contain the proper index processing codes. The input conversion attribute (att 14) of the attribute-defining item in the file dictionary is where they are specified.

Overloaded UP Commands for Data Files
Most UP commands work the same whether or not dictionary attributes are in control. Certain commands function differently when certain conditions are met. These commands provide the functionality for browsing on indexes. The cruising commands can be used in a double-clutching fashion by specifying the index for the current file and a second index for another file. <Ctrl>+u and <Ctrl>+y cruise on legal instances in the pointed to file staying in the same item. <Ctrl>+f and <Ctrl>+d cruise on other items in the same file using the index for the attribute as a guide.
<Ctrl> +
g When in an attribute which indexes to another file or has a translate code in the input processing code, this command pushes the current process one level and calls UP again with the item pointed to in the new file as the argument. If the macro attribute (attribute 15) in the primary file attribute definition item is used, this list is appended to the update statement. This is known as "zooming".
f On an indexed attribute, the sentence forward command goes to the next sequential index and gets the corresponding item into the UP workspace.
d On an attribute with an index, the sentence backward command goes to the previous sequential index and gets the corresponding item into the UP workspace.
u If the attribute indexes to another file, the word forward command gets the next sequential item from the pointed to file as the value for this attribute.
y If the attribute indexes to another file, the word backward command gets the previous sequential item from the pointed to file as the value for this attribute.
Related up.a

Command Verb: Access/TCL
Applicable release versions: AP 6.1, AP/Unix
Category TCL (746)
Description allows the setup and control of a hot backup configuration. Without any arguments a menu is displayed. This is the normal form of operation. See the section "hot backup, General", for a discussion of the important notions of the hot backup configuration.

Using the menus :
All operations are controlled through menus. If the terminal allows it, arrow keys can be used where indicated:
ENTER Validate the highlighted choice.
number From 0 to 9. Select the corresponding choice. '0' selects the option 10.
CTRL-N Move cursor down. (down arrow)
CTRL-B Move cursor up. (up arrow)
CTRL-X Cancel. Applicable only when input is requested.
ESC Quit. Go back to previous menu, or back to TCL. This key can be used to terminate all menus.
Q Quit. Go back to previous menu.
X Exit. Go back to TCL from any menu.

When the cursor is moved to a new field, a short help is displayed in the message area.

Screen layout :
The screen is divided in two sections:
- The menu section, where menus are displayed.
- The message section, where results, messages or help are displayed.

Definitions :
A background process. Servers work by pairs: one on each system.

The 'master' system is the main system, where users are normally working. By extension, the server running on the master system is the 'master server'.

The 'slave' system is the backup of a master system. By extension, the server running on the slave system is the 'slave server'.

Transaction log queue
All updates to the master system are not transmitted directly to the slave system. Instead, they are put into a 'transaction log queue' on the master system, which is emptied regularly by the master server, in a FIFO manner. In normal operation, this queue should always be very small. When a transaction is extracted from the queue, a transaction number is allocated for it. A transaction is physically removed from the queue only when the slave server has acknowledged it, so that, if anything goes wrong before the item, for example, is stored in the remote file, the transaction can be sent again to the slave.

Log slave updates
Normally, on a slave system, updates made by the slave server itself should not be logged in the transaction log queue. However, it is possible to set the system so that a slave system acts as a master system to another slave, to cascade updates. This is defined by the 'Log slave update' option.

Apply Updates
It is possible to instruct a slave server to NOT modify the database on the slave system. Updates received from the master system are NOT applied to the slave database. Instead they are stored in a temporary file. The purpose is to have a quiescent database on the slave system without having to stop the master system, to be able to do a full save of the data base, for example. Updates can then be re-applied to the slave database at a later time.

File and account auto-create
The slave database is supposed to be an exact image of the master database. However, optionally, the slave server will attempt to create any account or file missing on the slave system.

On the slave system, long operations, like clearing large files, are not done by the slave server itself, since it would not be able to process any incoming data. The slave server creates phantom processes (helpers) to help it perform these lengthy operations.

Large file creation
Files with a modulo larger than 100 are created in a special way. A smaller file (101) is created by the slave server itself, and a helper process is created to resize the file to its actual size. This has the advantage that the file is created almost instantly, thus becoming available on the slave system, without stopping the slave server. The slave server checks periodically on the helper to make sure it completes.

Temporary hold files
The slave server sometimes creates temporary files on the slave system to hold data it cannot store in their final destination immediately. For example, when a clear file command is received, a helper does the actual clearing, and a temporary hold file is used so that updates to the file being cleared received AFTER the clear command are not also delted.

D Pointer Controls :
In order to be able to write data in files, the slave server does some controls, and changes, on the file-defining D pointers on the slave system:
- Update protections are removed. This is to ensure that the slave server will be able to write into the file.

- CALLX correlatives are changed to use explicit path names to the subroutines. The account and file name where the subroutine resides is found in the cataloged object in the MD of the account where the file is located. If the subroutine is not found, the CALLX correlative is removed.

- Bridges to other files are controlled to use an explicit path to the target file. If the file cannot be found, the bridge is removed.

However, the amount of controls is necessary limited. A-correlatives are not controlled, and, obviously, references to files in BASIC subroutines are not controlled either. Therefore, if precautions are not taken, it is possible that the slave server will abort trying to update such a file. Note that NO data loss would occur, though, because the offending transaction will not be acknowledged and will be retransmitted. Starting the server with the traces ON, will identify which item and file causes the problem.

Installation :
Log on to the 'dm' account and type:
The first time this command is invoked, a server must be defined. The following menu is displayed:
Setup Server
1 New Server

Select and press <RETURN>

Type <RETURN> and fill in the appropriate information as explained in the section 'Setup Server' below.

Setup Server :
The 'Setup Server' menu is brought up automatically the first time 'hot-backup' is installed, or by selecting an option in the main menu.
Server name :
Any alphabetic string of up to 8 characters. This name will reference the server in all the other menus. If there is only one server defined on the Pick virtual machine, this server will always be implied in all commands.
Server type :
Master or Slave server. Depending on the server type, some fields of the remaining of the menu will become unapplicable.
Host name :
Master only. Name of the Unix host where the associated slave server is located.
TCP port number :
For a Slave Server, TCP port number, from 1024 to 32767, on which it is listening. For a master server, TCP port number of the associated slave server.
Protocol : inet
Cannot be modified.
Log slave update :
Slave only. If 'ON', all updates received by the slave are logged in the transaction log queue, to be sent to another system. If 'OFF', the updates are not enqueued. The default is 'OFF'.
Check period :
Master only. Period, in seconds, with which the master server will perform a variety of system checks. 0 disable all checks. A period of 300 seconds (5 minutes) should be suitable for most systems.
TxLog timer :
Master only. Period, in seconds, with which the master server will empty the transaction log queue. If the queue is not empty, then the server empties it continuously. If it becomes empty at some point, the master server goes to sleep for this period. A small value (2 or 3 seconds) is suitable.
Notify list :
List of Pick users or Pick port numbers to notify in case of error, separated by a comma. The port numbers are expressed in a syntax similar to the TCL command 'msg'. For example, to notify the users 'dm' and 'bob', and the line 0, whether it is logged on or not:
Apply updates :
Slave only. 'ON' or 'OFF'. Instruct the slave server to apply the updates it receives from the associated master server immediately (ON) or delay them (OFF) until it receives an explicit command. Normally, this option should be set to 'ON'. Note that, when later disabled, the server definition will be modified automatically. When the slave server starts, it will report the status of this option. Applying updates should not be disabled too long, since the slave data base is not an exact image of the master data base while updates are not applied.
Auto create :
Slave only. 'ON' or 'OFF'. Create automatically any missing account and file on the slave system. It is a good precaution to leave this option ON.
Comments :
Any text.

Confirm (y/n/q):
'y' to confirm the server creation. 'n' to go back to any of the previous fields. 'q' to quit and abandon.

Current Server Selection :
Most menu commands refer to a 'current' server, identified by its name. If there is only one server on the Pick virtual machine, then this server is always implied. If there is more than one server, the following menu is displayed when first entering 'hot-backup':
Operation title
Select and press <RETURN>

Type the selected number and <RETURN> to select a server. The 'current' server name is displayed under the hot backup header. In the following, 'selected server' will designate either the only server on the machine, or the current server selected by this menu. To select another 'current' server, hit 'ESC' or 'Q' back to the server selection menu.

Main Menu
1 Status
Display the last messages displayed by the selected server. The title of the message section on screen indicates the server name and additional information. The messages are displayed in reverse chronological order (most recent first). The server does not need to be running for this command.
2 Query Server
Query the selected server. The server must be running. See the section 'Query Server' below for the detail of the information returned.
3 Start Server
Start the selected server. This process displays various information about the starting of the server.
4 Stop Server
Stop the selected server. Confirmation is requested.
5 Show Server
Show the setup of the selected server. Type 'y' return to the main menu. The description of the displayed information is identical to the 'Setup Server' menu above.
6 Show statistics
Transaction statistics. If run on the slave server, the result is displayed immediately, if the server is running. If run on the master server, a request is sent to the slave server and displayed later. Both servers must be running. The response time depends on how busy the slave server is. This command is a quick way of determining whether the communication is established. The statistics are accumulated by the slave server and cleared every time it restarts.
7 Display Queue
Display the status of the transaction log queue. The following information is shown:
n frames in queue
DL or ALL files logged
File updates enqueued for all processes
File updates no longer enqueued
Current transaction: nnn
Last ACK'ed transaction: nnn
Current transaction: nnn
Upd itm '' in 'file.reference'
The number of frames is a rough indication of the amount of data not yet transmitted. The current transaction number is the transaction number being transmitted, if non zero. The last ACK'ed transaction number is the last transaction which was received and successfully processed by the associated slave server. If the last ACK'ed number is not reported, this means the query was done at a moment when all transactions have been acknowledged. The last line is an indication of the first transaction not yet acknowledged by the associated server. This can be an update item, a delete item, etc... In case of problem, this is the first transaction which would be retransmitted.
8 Special operations
Perform less frequently used operations. See the section "Special Operation Menu" below.
9 Transaction log menu
Control the transaction log queue. See the section "Transaction Log Menu" below.

Special Operations
1 Status
Display the last messages displayed by the selected server. Same as on the main menu.
2 Turn traces ON
Turn traces ON on the selected server. Traces are slowing down the server considerably and should not be left ON in normal operations. This is a debug tool only.
3 Turn traces OFF
Disable the traces on the selected server.
4 Setup Server
Setup a new server or modify the selected server. This the section 'Setup Server' above.
5 Delete server
Delete the selected server definition. Confirmation is requested.
6 List permanent log
List the permanent log of all messages logged by all servers. The log is shown in the message area on screen. Use the CTRL-N to see the next logs, and CTRL-B to go back in the log. Type ':' (colon) to enter a special command line which allows setting searching the first log entry after a given date or time, and search for a string. Type 'q' or ESC to return to the special operation menu.
7 Clear permanent log
Clear the permanent log file. A sub menu offers the choice of clearing the whole file, entries older than one week, or older than one month. Confirmation is requested.
8 Stop applying updates
Slave only. Instruct the selected server to stop applying updates coming from its associated master server. The updates are stored in a temporary hold file 'hb.log,apply'. The number of pending updates is shown in response to a 'Query Server' operation from the main menu. Updates can be applied by selecting the next option.
9 (Re)start applying updates
Slave only. Apply the pending updates to the database, if any, and restart the normal state of applying new updates as they arrive.
10 Close opened files
Slave only. The slave server maintains a list of all the files it has opened since it started. If it becomes necessary to delete a file on the slave system, or after recovering from a missing file-of-files item on the master system (see the discussion below about the error message 'Cannot read FOF item'), the slave server must be instructed to close all the files it has opened. This option allows this. If the files are accessed again, the slave server will re-open them.

Transaction Log Menu
The transaction log menu should be used on a system which is setup as a master system. It controls what and how updates are transmitted to the associated slave system.
1 Display queue
Display the status of the transaction log queue. Same as option 7 on the main menu.
2 Log DL files only
Log only the files which have a DL attribute in the D pointer. This option affects the entire system. This mode of operation allows fine control over what is being sent to the other system.
3 Log ALL files
Log updates to all files on the system. Note the slave server will NOT apply any modification to selected files in the 'dm' account on the slave server: abs, accounts, devs, errors, file-of-files, hb.log (hot backup control files), jobs, pibs resizing. This option should be used with caution, since the slave server may create accounts and files to receive data.
4 Stop enqueuing
Stop enqueuing updates. Confirmation is requested. This option should be used with extreme care, since, once selected, all updates to the master data base will NEVER be transmitted to the slave system. The only legitimate use of this option is to stop enqueuing updates following a major problem on the main system which required switching users to the slave system. This event is also logged in the 'errors' file.
5 Start enqueueing
(re)Start enqueuing updates. This event is also logged in the 'errors' file.
6 Clear log queue
Clear the transaction log queue. Confirmation is requested. All queued updates are lost. This event is also logged in the 'errors' file.

Query Server Results :
On a Slave server, the following information is displayed:

Server <servername>. PIB <pib>. PID <pid>. Server type [Slave|Master]. Traces [ON|OFF].
Total [recvd|sent] 289K. {Cur trans 1041.} ACK'ed trans 1039. {updates {NOT} applied.}
{n file(s) failed to open successfully}
{n pending update(s)}
Status <status>


Name of the server.

Pick port number of the server.

Unix process id of the server.

Cur trans
Slave only. Current transaction number received by the slave server. This number should increase as data is exchanged between the servers.

ACK'ed trans
Current transaction number successfully acknowledge by the slave server. Unless the queue is empty, the ACK'ed transaction number should be slightly less than the transaction number received by the slave.

{updates {NOT} applied}
Slave only. If present, indicates whether updates received from the master system are currently applied to the slave database.

Total [sent|recvd]
Total size, in kilobytes, received for the current day. Note the master reports a slightly higher number than than the slave, due to additional protocol information.

{n file(s) failed to open successfully}
Slave only. If present, indicates that the slave server received requests to open files and was not able to do so. At any given time, there may be a few pending open files, so repeat the command to make sure there are some problems. Examine the permanent log file to get more information.

{n pending updates}
Slave only. If present, indicates that the updates to the slave data base are currently disabled, and that there are 'n' pending updates.

Server status:

Reading network
This is the normal state of the slave server.

Wait response to call
Master only. The master server is attempting to call its associated slave.

Wait incoming call
Slave only. The slave server is waiting for its associated master server to establish a communication.

The server has stopped. The previous message in the status or permanent log file would indicate the reason of the termination.

Intermediate state right after a connection is established.

Writing to network
Sending data to the associated server. If this state persists and no data transfer occurs, this indicates the receiver is not reading data. There is a 30 second time out after which the connection will be shutdown and restarted.

Waiting for ACK
Master only. Wait for an acknowledgment from the associated slave server.

Master only. The queue is empty and there is no traffic.

Reading queue
Master only. Intermediate state while the master server is extracting messages from the transaction log queue.

Non Menu Operation :
It is possible to perform some operations from TCL by specifying a 'command' on the TCL line. If there is more than one server, the server must be specified by '' argument. This for is useful to perform some automatic commands in macros.


Start the specified server.

stop the specified server.

Display the status information (same as option 1 on the main menu) of the specified server.

Display the transaction log queue information (same as option 7 in the main menu).

Force the specified server to enter the BASIC debugger. This option is for testing only. The server can then be debugged using tandem.

Main Error Messages :

This section lists the main error or warning messages that can either be displayed in the message area or logged in the permanent log file.

ERROR: This command applies only to Slave servers
This command can only be used when selecting a slave servers. Some function cannot be performed by master servers.

Not a phantom. Running on PIB xxx. PID yyy
This message can appear when interrogating a server which is either started in foreground (for debugging purpose) or, most likely, which has aborted, or was killed, and left an inconsistent status in the jobs file.

Terminated abormally
The server phantom process has terminated, but without finishing properly. The process was probably logged off, or encountered an fatal error.

Notice from server 'servername'
The message in the message area is coming from the specified server.

Waiting for server 'servername' to start
Wait for the phantom process to start.

Waiting for server 'servername' to initialize
The phantom process has started and now wait for the server to initialize itself.

FAILED: Cannot start phantom process
The phantom process failed to start. Check the scheduler, make sure there are not too many queued jobs. Use 'list-jobs' to determine the cause of the abort.

FAILED: Server 'servername' encountered an error and stopped
The phantom process started normally, but the server could not complete its initialization. Use the 'status' menu option to see the cause of the failure. The most common cause is a 'BIND' error, indicating that the TCP port is already in use. Often, when stopping a server, the TCP connection is not purged immediately and the TCP port number remains in use. This usually cleans up by itself after the various TCP protocol time outs have expired. Stop the master server. Retry a few minutes later. If the BIND error persists, change the port number using the 'setup' option, on BOTH the master and the slave sides.

WARNING: Server 'servername' is already running on PIB xxx
A start server failed because the server appears to be already running. This has no action on a running server. If the server is NOT running, and this message still appears, this might indicate a corruption of the hot backup control file. Make sure the server is not running (using where) and do:
delete hb.log servername

WARNING: Transaction are NOT enqueued
This warning is issued by the master server to indicate that updates to the data base are not being enqueued, and therefore not being transferred to the slave system. The databases are now different.

WARNING: Transaction queue has grown to xxx frames
Periodically, the master server checks if the queue has grown to more than 500 frames above the previous value. This message is an indication that the slave server is not able to keep up. Make sure the input server is not stopped, or has not aborted. This message MAY be normal in exceptional situations where massive updates are being done.

malloc error. err=xxx
The system could allocate memory. This is an indication of a serious Unix problem. Check the swap space.

socket creation failed
The socket library is not linked properly to the Monitor being run by the phantom. Refer to the installation guide to link the proper socket libraries fro implementation for which this library is an optional package.

Cannot call host 'hostname'. Errno=xxx
The master server cannot establish a communication. 'xxx' is an indication of the error. The error code is very implementation dependent. Make sure the host is reachable by using the Unix command 'ping hostname'. If so, the most likely reason is that the slave server is not started or has encountered an error. Use the status menu option on the slave.

Cannot read FOF item 'xxx'
Due to a corruption in the file-of-files file on the master system, the system is unable to identify the file being updated. 'xxx' is the file number (as known on the master system). Data is normally transferred to the slave system but stored in a temporary hold file named "hb.missing,mastername*xxx", where 'mastername' is the name of the master server, and 'xxx' the file number. To correct this situation, the file-of-files file on the master system must be rebuilt by doing a full file save (possibly a dummy save), with the (S) option. The missing fof item can also be rebuilt by hand if the file name can be identified from the content of the file being stored in the temporary hold file on the backup system. The data can then be copied to the real file. Instruct the slave server to close its opened files, using the special operation menu, to force it to open the new file.

Lost+Found File :
When a slave server is unable to process a transaction (for example, the account does not exist and the automatic creation of missing accounts is disabled), the transaction is stored into the trash file 'hb.log,lost+found'. The item-ids of this file are unique timedate stamps. This file can be used to recover the salvaged data. The format of an item is:

1 Item type:
1: Unknown transaction code.
2: Slave server was reset.
3: Internal error.
4: Time out on transaction. These errors can occur when stopping the master server.
5: Bad network message.
6: Cannot perform the operation. The error message usually indicates the cause of the problem.
7: D pointer can not be updated. There is a D pointer like element in the master dictionary or file dictionary preventing the creation of the file. This item was deleted to allow the file creation and its content written starting at the attribute 10.
8: The MD of the account in which the slave server is running (normally 'dm') contains an item which collides with the name of an account. Though this is normally authorized, this is not a good practice. The server removes this item and dump the content of this item.
9: The slave server removed a correlative from a D pointer because it could not resolve a reference to a CALLX subroutine or to a bridge. The lost+found item contains the removed correlative.
10: Transaction could not be processed when applying delayed updates.
11: Incorrect transaction length.
2 Transaction opcode, if applicable, or '?'.
3 Server name.
4 Log internal time.
5 Log internal date..
6 Transaction number.
7 Last ACK'ed transaction number.
8 Message.
9 Time date in external format.
10 Body of the transaction which could not be processed or any data the server could not handle. More than one attribute can be used. This data may be incomplete.
Syntax hot-backup {{command} {server=name}}
Options Q Quiet. Valid only for the non menu operation. Supresses all messages.

V Verbose. Turn traces on when starting the server from the menu.
Examples :

  Enter the main menu.

hot-backup start
  Start the (only) server on the virtual machine.

hot-backup start server=todev
hot-backup start server=fromprod
hot-backup status server=todev
hot-backup status server=fromprod
  On a system which is both slave and master, start a master server 
'todev' and a slave server 'fromprod'. Obtain status from 
both of these servers.


Command tcl.export Verb: Access/DOS
Applicable release versions: AP/DOS, AP/Native
Category DOS (25)
Description converts Advanced Pick files on either AP/DOS or AP/Native systems to a DOS format in a DOS file.

"file.reference" is the source Pick file name.

"" is the item to transfer. If no item-id is entered, then the system will ask: "Selected Pick Item:".

"dir.path" is the path to the DOS directory into which the file is to be copied. If none is specified, it defaults to the current working directory.

"DOS.file" is the name of the MS-DOS file to which the Pick item will be copied. Complete pathnames must be used if the files are not to be copied into the current working directory. If the name of the destination file is not provided, the item-id is used as the name of the destination file.

If a directory is specified, no spaces may be specified between "dir.path" and "DOS.file". The directory must be preceded by a "". For example: c:pickdosfile.pik

By using an active select list, multiple items can be transferred.
Syntax export file.reference {(options}
to: {dir.path}{DOS.file}
Options c Concatenate Pick item(s) into one DOS file. Items will not be separated by any character, unless the E-option is used.
e Append item delimeter to each Pick item. Only takes effect when used with the C-option. The system will ask: "Enter record separator (in hex):" for a (single) separator character between items.
i Includes item-ids as the first attribute (field) in the destination file.
k Disables conversion of attribute marks to cr/lf characters. To convert attribute marks to some other (single) character, use the 't' option below.
n Sort items before exporting.
o Overwrite dos file, if a duplicate exists.
p Directs output to the system printer, via the Spooler.
s Use Pick ids as dos file names.
t translate specific (single) characters to new (single) characters. The system will ask: "Replace: ". The user enters the ASCII value (in hex) of the character to scan for. An entry of <cr> will quit the replace session. The system will then ask: "With: ". The user enters in the new replacing ASCII value (in hex). The system will ask for up to 15 additional characters to replace. If the same character is entered twice, only the most recent entry is used. The system will finally ask: "OKAY(Y/N): ". An answer of "Y" indicates all the entries are correct. An answer of "N" will wipe out all the entries and start over.
export cust * (cinokte
Preparing item to export, please wait...
[404] nnn items selected out of nnn items.
Enter DOS record separator in hex: 0c
Replace: FE
With   : 2C
Replace: FD
With   : 5F
Replace: <cr>
Selected pick item(s) to Dos File Name: B:CUST.DAT
Copying data to DOS, please wait...
   nnnnnn bytes copied
MS-DOS file 'B:CUST.DAT' created.

This will:
  export all the items in the pick file "cust",
  write it to the DOS file "CUST.DAT" on the B: drive,
  concatenate all the items into one file,
  export the item-id along with the attributes,  
  sort the cust file first before exporting,
  overwrite any previously existing DOS "CUST.DAT" file,
  don't convert attribute marks with a carriage return / line feed,
  replace all the attribute marks with a comma,
  replace all the value marks with the underscore character, and
  replace the item delimiter with a carriage return (but no line feed).
Related tcl.import


Command ue.007a User Exit/BASIC Program
Applicable release versions: AP 6.1
Category BASIC Program (486)
Description updates a binary item from a Pick/BASIC program.
The file in which the item is stored is referenced by the last open or last file access preceding the call. See the examples below.

Item-id of the binary item.

Since a Pick/BASIC program cannot handle segment marks (decimal 255) characters, a special encoding scheme is used. A segment mark is replaced by the special two character sequence 'DLE _', where DLE is a 'data link escape' character (decimal 16) and '_' the underscore character. The following special sequences are replaced at file time:
DLE DLE Replaced by one DLE.
DLE _ Replaced by one segment mark.
DLE XX Replaced by one or more segment marks, where 'XX' is the number of segment marks from 1 to 126, plus 128 (hex x'80'). For example, DLE x'81' is replaced by one segment mark, DLE x'A3' is replaced by x'A3'-x'80'=x'23'=35 segment marks.

Item body size, in decimal. The size does not include the special DLE escape sequences, but it should includes the number of segment marks after decompression. In other words, it is the size as if the item body was not encoded with DLE sequences. If the size is not large enough, additional overflow is allocated to hold the binary item, but this space is not contiguous in the Virtual space, which may have some impact on performance while accessing the binary item.

Return code:
>0 Number of frames allocated to hold the binary item.
-1 Not enough overflow.
-2 Illegal DLE sequence.
-3 Illegal file reference.
Syntax code=oconv(size^^item.body,"u007A")
equ DLE to char(16)

open "dict","object" to fd
code=oconv(2:AM:'test':AM:x, "u007a")

Write a binary item 'test' containing the TWO characters (in hex) 
x'01ff' in the dict of the file 'object'. 'code' 
returns 1 frame allocated. 

equ DLE to char(16)

read dummy from fd,'' else dummy=''
code=oconv(33:AM:'test':AM:x, "u007a")

Write a binary item 'test' containing 32 consecutive segment marks, 
followed by one DLE, in a file described by the file descriptor 'fd'. 
Note how the read of a dummy (possibly non existent) item is used to 
'reference' the file.

Command Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP, R83
Category BASIC: Syntax (110)
Description references attribute 0 of the current item being processed by Access.
Related tcl.add-font