op.font Command/Output Processor: Commands, basic.debugger.overview Introductory/BASIC: Debugger, prestored.commands Article/Article, t-verify.messages Article/Article, tcl.import Verb: Access/TCL, external.format Definition/General, tcl.ap.unix Verb: TCL2/Unix, updte.processor Definition/Update Processor, tcl.set-port Verb: Access/TCL, basic.%connect C Function/BASIC Program, internal.format Definition/General, basic.%bind C Function/BASIC Program, legal Introductory/Access: Modifiers, sdb Definition/Unix, runoff.read Command/Runoff: Commands, access.with Modifier/Access: Verbs, maxfid Definition/General, pc.d Processing Code/Restore Processor, pc.o Processing Code/Restore Processor, filename.errors Definition/Access: General, system.debugger.functions Definition/System Debugger, tcl.config.options Menu/TCL, screen.input Subroutine/BASIC Program, signals Definition/Unix, tcl.update-md Verb: Access/TCL, basic.$options Statement/BASIC Program, access.phrases Definition/Access: Verbs, up.prestore Command/Update Processor, ue.$uex.rel.buf User Exit/BASIC Program, pa Definition/General, update.processor Definition/Update Processor, basic.cfunc Definition/BASIC Program, access.total Modifier/Access: Verbs, tcl.spelling.checker Definition/Update Processor, up Introductory/Update Processor, tcl.:ent-link Verb: Access/TCL, ue.007a User Exit/BASIC Program, pc.mt Processing Code/Restore Processor, legal Introductory/Access: Modifiers

op.font

Command op.font Command/Output Processor: Commands
Applicable release versions: AP
Category Output Processor: Commands (183)
Description selects the font defined in the device item or specifies fonts that are not predefined in the printer item.

The "number" selects the corresponding font number defined in the device item. (See the "devices" file).

"orientation"
may be either "portrait" or "landscape"

"symbolset"
may be either "ASCII", "legal", "roman8" or "linedraw".

"spacing"
may be either "proportional" or "fixed".

"pointsize"
specifies the point size.

"pitch"
specifies the pitch.

"style"
may be either "upright", "italic" or "reverse".

"strokeweight"
may be "light", "lightmedium", "mediumlight", "medium", "mediumbold", "boldmedium" or "bold".

"typeface"
may be any of the valid types defined in the corresponding item in the "devices" file for the printer being used. (For an example, see "hp-lzrii" in the "devices" file).

If the device does not support fonts, or the device item has not been configured, this command has no effect.
Syntax .f{ont} number
.f{ont} orientation, symbolset, spacing, pointsize, pitch, style, strokeweight, typeface
Options
Example
.font portrait,legal,fixed,10,12,upright,medium,courier
Purpose
Related tcl.download
op.f
tcl.pitch-compile
op.reset
tcl.setup-printer
filename.devices
op

basic.debugger.overview

Command basic.debugger.overview Introductory/BASIC: Debugger
Applicable release versions: AP, R83, AP 6.0 FlashBASIC
Category BASIC: Debugger (38)
Description facilitates the debugging of new Pick/BASIC programs and the maintenance of existing Pick/BASIC programs.

The Pick/BASIC debugger has the following general capabilities:

1) Step through execution of program in single or multiple steps. (see the "e" command).

2) Transfer to a specified line number. (see the "g" command)

3) "Break" execution (temporarily halt) at given line numbers or when specified conditions have been satisfied. (see the "b" command)

4) Display or change any variables, including dimensioned variables. (see the "/" command).

5) "Trace" variables. (see the "t" command)

6) Enter the system debugger. (see the "de" and "debug" commands)

7) Direct output to either terminal or printer. (see the "lp" command)

8) Display and/or pop GOSUB stack. (see the "r" command)

9) Display source code lines. (see the "l" and "c" commands)

Note: sys2 privileges are required to use the Pick/BASIC debugger.

When the Pick/BASIC debugger is entered, it indicates the source code line number to be executed next and prompts for commands with an asterisk (*).

Symbol Table:

When a Pick/BASIC program is compiled, a symbol table is generated, unless the "s" (suppress table) option has been used with the "compile" or "basic" verb. The symbol table is stored as part of the object code and is used by the Pick/BASIC debugger to reference symbolic variables.

If a program calls an external subroutine, and the Pick/BASIC debugger has been entered previously, a complete symbol table is set up for the external subroutine.

Entering the debugger: There are several ways to enter the debugger. Some of them are voluntary. Among the voluntary methods are:

1) Pressing the "break" key while a Pick/BASIC program is executing.

2) Running the program with a "d" option:

run bp enter.customer (d)<return>

If the program is cataloged, a "d" option may follow the program name at TCL:

enter.customer (d)<return>

3) Placing a "debug" statement within the program at the point where the debugger is needed.

4) Running the program with a "e" option, which "breaks" at any "non-fatal" warning message:

run bp enter.customer (e)<return>

If the program is cataloged, an "e" option may follow the program name at TCL:

enter.customer (e)<return>

The other ways of entering the debugger are, of course, involuntarily. This occurs if a runtime error is encountered (unless the "a" (abort) option of the "run" verb is selected), or if an "abort" statement is executed in the program.

The "*" (asterisk) character is used as the Pick/BASIC Debugger prompt character. When it appears in the leftmost column of the terminal display screen, this indicates that the debugger is ready to accept any legal command. The number of "*" characters indicates the current level.

"Breakpoints" may be set in the debugger. A "breakpoint" is a conditional expression constructed with a symbol reference (one of the variables from the program), an operator (like "=" or "#"), and a specific value. For instance: item-id#"" sets up a conditional to break into the debugger when the variable "item-id" is non-null. (see the "b" command)

Break points set up for a subroutine are independent from break points set up in the main program or other subroutines; however, the execution counters "e" and "n" are global. That is, the break point counters count both main program and subroutine break points in the order they are encountered. The use of multiple symbol tables allows the programmer to set up different break points and/or variable traces for different subroutines. (see the "e" and "n" commands)

Operators are used to perform relational comparisons and are used with the "b" command for setting breakpoint conditions. The valid operators are as follows:

= equal to.
> greater than.
< less than.
>= greater than or equal to.
<= less than or equal to.
# not equal to.

Referencing variables : once in the debugger, the current value of any variable may be interrogated (and optionally changed) using the following forms:

*/variable

This accesses a plain variable and displays its current value.

*/dim.array.variable(subscript)

This access a single-dimensioned array variable. With the subscript designated, only that element is displayed.

*/dim.array.variable<return>

If a dimensioned array is referenced without a subsrcipt, each element is displayed. Another <break> while in this mode exits this display without stepping through all the elements.

*/dim.array.variable(n,n)

This accesses a specific location of a two-dimensional array. See the above form for array references without subscripts.

*/*

This displays the current assignment of every variable in the program.

In each of the above cases (except the "*" form), the operator is given the opportunity to change the requested value. If a <return> is entered at the "=" prompt, the symbol remains unchanged. Otherwise, any value entered is placed into the symbol.

Zone output specification :

*[{left.limit,right.limit}]
-or-
*[

The "zone" command sets left and right output zone limits of debugger display. Both "limit" arguments must be numeric, and it is advised that the second argument be larger than the first. The "["command, followed by a <return>, removes zone limits.
Syntax
Options
Example
Purpose
Related basic.debugger.r
basic.debugger.b
basic.debugger.d
basic.debugger.e
basic.debugger.g
basic.abort
basic.debugger.k
basic.debugger.l
basic.debugger.u
tcl.run
basic.debugger.debug
basic.debugger.t
basic.debugger.z
tcl.basic
tcl.compile
basic.debugger.variable.references
basic.debugger.lp
tcl.debug
basic.debug
basic.debugger.c
basic.debugger.de
basic.debugger.n
basic.debugger.?
basic.debugger.s
flash.basic.differences
basic.debugger.down
basic.debugger.edit
basic.debugger.return
basic.debugger.up
basic.debugger.?!
basic.debugger.$!
basic.debugger.
fatal.error.condition
non.fatal.error.condition
basic.debugger.p
basic.debugger.#
basic.debugger.[]
basic.debugger.help
prompt.chars.ap
<ctrl>n

prestored.commands

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.

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

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

"account.name,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.

UP COMMANDS ACTION

<ctrl>+zl Edit prestore command

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

<ctrl>+zr{(file.reference}item.id<ctrl>+m Loads prestore command or <ctrl>+zr{(file.reference}item.id <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:

:P

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.

Example:

<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 :

'prestore.id' 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 document.id 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 document.id 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,item.id, 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.

Example:

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:

Command:

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
Syntax
Options
Example
Purpose
Related

t-verify.messages

Command t-verify.messages Article/Article
Applicable release versions: AP
Category Article (24)
Description T-verify error message explanations.

Originally ran in PickWorld Magazine under the title: "WHAT IS T-VERIFY TELLING ME?".

[1502] Illegal file level for 'D' pointer
A d-pointer was read from the tape, but the file level number was not valid. It could have been garbage. Do not rely on this tape.

[1503] Illegal file ID for 'D' pointer
A d-pointer was read from the tape, but the file id (file number) was not valid. It could have been garbage. The file ID is taken from the file-of-files file. Do not rely on this tape.

[1504] Illegal character count for 'D' pointer
A d-pointer was read from the tape, but the count field was not a valid 4 byte hex number (ASCII hex). It could have been garbage. Do not rely on this tape.

[1505 Character count too small for 'D' pointer
A d-pointer was read that had a count field that was too small for the number of characters actually read. The d-pointer body has been corrupted or the count field is wrong. Do not rely on this tape.

[1506] Item-ID too large for count field in 'D' pointer
A d-pointer was read from the tape, but the whole d-pointer is just an Item- ID. Maybe it got truncated or overwritten. Do not rely on this tape.

[1507] Item-ID too small for count field in 'D' pointer
A d-pointer was read from the tape, but the whole d-pointer is just an Item-ID and ended prematurely (too small). Maybe it got truncated. Do not rely on this tape.

[1512] Non decimal modulo for 'D' pointer
A d-pointer was read from the tape, but attribute 3 does not have a decimal number in it. Maybe garbage was read. This invalidates this item as a d-point er. Do not rely on this tape.

[1513] MDS 'D' pointer expected
A T-VERIFY on a full save tape was begun, but the mds d-pointer was not found at the beginning of the 1st reel. Maybe an account-save tape was insert ed or the 1st reel was not rewound to the beginning. The file-system has not been checked at all yet.

[1515] Illegal file level for MDS 'D' pointer
The mds d-pointer has a file level of zero. Zero is the highest level. This is the only file that is at this level. This is not a valid full save tape. No statement can be made about the file-system (disk).

[1516] Mismatching MDS 'D' pointer
The mds d-pointer read from the tape does not match the one on disk (in the file-system). The tape is intact and restorable, but does not reflect the current state of the system.

[1520] Non hexadecimal file ID
Every item on the tape has a file number with it that tells which file it came from. This field is supposed to be ASCII hex! For some reason, it is corrupt and not ASCII hex. The restore processor might have trouble restoring it. Do not rely on this tape.

[1523] Count field too small for item
The item read from the tape has more characters than its count field indicates. The data might still restore properly, but do not rely on it.

[1524] Item-ID too large for count field
The whole item was just an Item-ID and it was too small for its count field. Maybe it got truncated. The count field (character count) was wrong. This one item was bad and maybe garbage. No Item-ID is displayed because T- VERIFY could not guarantee it found one.

[1525] Non hexadecimal binary code block count
Every binary item (basic object code) on the tape has a block count associated with it. Binary item data is placed on the save tape 1000 bytes per block. This hexadecimal field is corrupt. If this message occurs on only one item, than just recompile the item from the source program. If many messages occur, then do not rely on this tape.

[1526] Attribute mark missing after Item-ID
The item read from the tape was only an Item-ID and was terminated by a segment mark. This is not normal but the item will restore properly. Check the item on disk. The tape is intact. No statement can be made abut the file- system (disk).

[1527 Count field missing
The item read from tape has no 4 byte count field and it is not a pointer item or a binary item (those types do not have count fields). The item might restore or it might be garbage. Do not rely on this tape. No statement can be made about the file-system.

[1549] File on tape not on disk
A d-pointer item was read from the tape. It is fine, but there is not a file on disk with the same name. The tape is intact, but does not reflect the current state of the file-system.

[1552] Binary code missing inter-block delimiter
Advanced Pick dumps binary code as a binary frame dump. Each frame has a 1 byte separator on the tape. This byte is missing, or a block was lost or garbage was read. Something is wrong with the tape. Do not rely on it.

[1553] Binary code missing final segment mark
On the tape, after the last block of object code of a binary item, there is a segment mark. This one is missing. It will probably restore correctly, but you might lose the next item on the tape. Maybe a block was lost from the tape. Do not rely on this tape.

[1565] Data level is in the process of being deleted
You cannot verify a file against the disk if it is being deleted. the tape is still intact, but does not reflect the current state of the file-system.

[1566] Dictionary is in the process of being deleted
You cannot verify a file against the disk if it is being deleted. The tape is still intact, but does not reflect the current state of the file-system.

[1567] Account is in the process of being deleted
You cannot verify an account if it is in the process of being deleted. The tape is intact and can be restored from, but does not reflect the current state of the file-system.

[1588] Label missing
A label is expected prior to each account. The tape is corrupt or was not posi tioned at the beginning prior to running T-VERIFY.

[1591] Illegal file ID of zero
Every file has a number associated with it. For some reason, a file has been read from the tape that has a file number of zero. Check the file-of-files file for a zero Item-ID. If this is the only tape error, then the tape is probably restorable, but don't rely on it.

[1593] Illegal file number for index b-tree
An index b-tree was read from the tape, but T-VERIFY cannot determine what file it belongs to. The tape is corrupt. Do not rely on it.

[1594] Index will not restore, different frame size
The save was made on a machine with a different frame size. The tape is intact and restorable, but all index b-trees will be skipped and will be generat ed new at the end of the restore. This is because, like binary items, the b-trees are dumped to tape in binary images, frame by frame.

[1596] Index b-trees mismatch
The index b-tree read from the tape is intact and restorable, but does not match the one in the file-system. Maybe the index on disk was updated. The tape is fine.

[1598] GFE(s) encountered
While comparing the tape against the disk, a GFE was encountered and skipped. The tape is intact, but the file-system has data corruption.
Syntax
Options
Example
Purpose
Related tcl.t-verify
pointer.item

tcl.import

Command tcl.import Verb: Access/TCL
Applicable release versions: AP/Unix
Category TCL (746)
Description imports Unix files to Pick items.

<New line> characters are converted into attribute marks. The source Unix files are either specified explicitly or are specified by the directory on which they can be found.

"file.reference"
Destination Pick file name.

"item.list"
List of the destination items. If not specified, a list must be active.

"dir"
Directory where the source files are to be found. The filenames are the same as the item-id(s) from the source list. The "l" option is used to convert Unix filenames to lower case.

"unix.file"
Explicit list of the source Unix files. Complete pathnames must be used if the files are not on the current directory. The current directory may be changed by the "cd" command. If no source list is provided, the destination list is used as a source list also. Wild cards are legal in unix.file, but in this case, all the files are concatenated before the copy.
Syntax import file.reference {item.list} {(options}
from :[ dir |{unix.file {unix.file} ... } ]
Options en Expands Unix tabulations into "n" spaces. If "n" is not specified, the default is 4. Tabulations expansion is done using the pr(1) Unix command.

i Suppresses display of item-id(s).

l Converts unix.file name in lower case before doing the copy.

O Overwrites Pick item(s), if duplicate item-id(s) encountered.
Example
Purpose
Related tcl.add-font
dos.copypick
filename.kb.fk
tcl.set-kbrd.sco
tcl.copydos.r83
tcl.export.r83
dos.copypick.r83
tcl.export.unix
tcl.export

external.format

Command external.format Definition/General
Applicable release versions: AP, R83
Category General (155)
Description describes data that has been "externally converted" using one of the "conversion" or "processing" codes provided with Pick. As a general rule, "external format" means data is in a "human-readable" format.

The main advantage of an "internal" format is that it takes much less time to compare two values.

For instance, time values are not stored as the human readable form. Rather, they are converted using the "mt" input processing code, which takes a legal "external" time such as "14:00" (2:00 p.m.) and calculates the number of seconds past midnight for this value, which would be the "internal" value. In this case, the "internal" form would be "50400". The same "mt" code used as an output processing code may be used to convert the internal value to its "external" form.

Dates are also more easily manipulated if stored in an "internal" format. A input processing code of "d" will take an external date, use a calculation to determine the number of days that have elapsed since December 31st, 1967 (day 0 (zero) on the Pick calendar), and store an "internal" julian date. A similar output processing code will convert an "internal" date to its human-readable "external" form. See the date processing codes for the various output formats available.

In addition, numerical values are more easily handled by the system if they are all stored as integer amounts, and the decimal point (if any) is inserted only upon output. Typical American dollar amounts, say, "$100.00" is converted upon input to an "internal" form of "10000" using the "MR2" input processing code. A similar output processing code will re-display the figure as "100.00". See the "m" processing codes for all its variations.

One final reason for using an "internal" format is to save storage space. Such an example would be to convert the external form of "SMALL", "MEDIUM", and "LARGE" into "S", "M", and "L". The internal values can them be re-constituted upon output.
Syntax
Options
Example
Purpose
Related internal.format
pc.mt
processing.codes
pc.d

tcl.ap.unix

Command tcl.ap.unix Verb: TCL2/Unix
Applicable release versions: AP/Unix, AP 6.0
Category Unix (24)
Description starts the Pick virtual machine or a Pick user process.

-0
Starts the virtual machine. This process has the responsibility to initialize the virtual machine. All other processes will wait for the coldstart to complete its initialization before actually starting. Once the virtual machine is started, the line 0 can be disconnected, by typing 'exit' or 'disc', on any other line. Issuing 'ap -0' again will simply reconnect to the virtual machine if is is booted.

-a bootarg
Starts a virtual machine automatically. This process has the responsibility to initialize the virtual machine. All other processes will wait for the coldstart to complete its initialization before actually starting. This option is similar to the "0" option, with the difference that the system does not prompt for a boot option. Instead, it takes one-character commands from "bootarg" among the boot options: "x", "f" or "a". When encountering the "x" command, the system polls the keyboard for a period of "bootsleep" seconds (the default is 3 seconds) for a user intervention. If any key is pressed during this short period, the system defaults to a manual boot. "bootsleep" can be redefined in the Pick configuration file, by adding the statement 'bootsleep n' or by using the TCL command "config options". "bootarg" is a string of commands as if typed by the operator for a manual boot. When the command involves a tape, the tape is assumed to be ready. Therefore, the "c" for continue should not be included in the string.

- port.number
Starts a user process. Expressed in decimal from 1 to the maximum allowed number of users, this starts a Pick process on a given port when it is necessary to control the port on which process is running. If the port is not given the system allocates the first available port.

-q
Query. This command can be executed by any process to get information about the specified virtual machine. If the virtual machine is started, then the command returns exit code "0" to the shell, otherwise a value of "1" is returned. This allows testing the existence of the virtual machine from the shell.

-k
This command kills all processes attached to the specified virtual machine. First, a Pick logoff is attempted, followed by a terminate signal, which should send the process back to Unix. If the terminate signal has no effect, a kill is attempted which removes the process. This command should be used only in extreme situations. This is not a normal way to stop a virtual machine.

-n configfile
This specifies the name of the configuration file. If not given, the default file name is "pick0" in the current directory or alternately in the "/usr/lib/pick" directory.

-t tty
This option specifies which port is to become the terminal for the process. The device is assumed to be on the "/dev" special files directory. If not specified, the terminal is "stdout/stdin", unless it has been redirected, (the usual case on AIX systems). This option is normally intended to be used only in the "/etc/inittab" file. When this field is present, the system assumes the user process is started automatically, and, behaves a bit differently when starting: it waits for line 0 to start, if it is not started already.

-y sttyarg
This option allows changing the default port setting for the process. "sttyarg" is any "stty" argument. If more than one element is changed, they must be separated by spaces and the whole argument enclosed between double quotes (see examples below). When the process terminates, the port characteristics are not reset to their original values.

-d dataarg
This option allows stacking data for the process once it is activated. "dataarg" is any string which contains displayable characters and commands prefixed by a back slash (). Note that the string is subjected to the normal shell parsing, thus, back slashes must be "escaped", or the entire string must be enclosed in single quotes. "dataarg" can be contained in a Unix file by using the shell command substitution mechanism (e.g. using "back quoting" mechanism: -d ~` cat /usr/lib/pick/logon~`). All line feeds in the input string are converted to carriage returns.

The 'dataarg' commands are:

r Insert a carriage return.

f Turn echo off. The stacked data will not be displayed.

n Turn echo on. The stacked data will be displayed.

m Wait until the Pick virtual machine enters multiuser mode. The "maxusers" TCL command should be included in the "user-coldstart" macro after all system and application initialization are completed.

Insert a back slash.

When activating a process for the first time, the system reads one character, then empties the type ahead buffer. Therefore, stacked data should always start by the sequence r, followed by the real logon sequence.

-l
Retains login Unix user-id. This option logs the process as the same Unix user as the one used to log in to Unix. This option overrides the user definition contained in the configuration file. A Pick process started with this option does not have access to the Pick spooler, nor to the message facility (or at least very restricted). The user is in some way isolated from the other Pick users. This option should be used only for users who want their own Unix environment underneath the Pick process or to do system configuration which requires 'root' access.

-D
Enables Monitor Debugger. On entry, the process enters the Monitor Debugger. This option is ignored if the process started is a phantom or a printer. Type g<return> to actually start the process.

-s
Enables "silent" mode. If used along with the "-0" command, the Pick machine will boot, and return directly to Unix. If used on a normal line, output of logon and logoff messages and user macros is suppressed and any attempt to logoff will return directly to Unix. Because output is supressed, the "-s" flag must generally be used along with the "-d" flag followed by a string containing the user name, user password, MD, and MD password when applicable so that the user is logged into Pick automatically. The "-s" flag is used by the "tcl" Unix shell script.

-i nice
Set the relative priority of the Pick process, compared to other processes, Pick or not, running on the system. Legal values of 'nice' are -20 to +19. -10 gives the highest priority, +19 the lowest.

-W
Wait for the device specified by the '-t' option to be created. Available only on AP 6.1.7 or later. This option instructs the Pick monitor that the device does not exist yet, thus avoiding the 'no such file' error. This is used in configurations where the '/dev/' entry is created dynamically by a Unix daemon (for example on HP-UX using a DTC). The process polls the specified device and waits until it is created as a pipe or block or character device. This option is ignored if the '-t' option is not specified as well.

-printer
This option specifies that the port is to be used as a printer. It suppresses the messages 'Connected to virtual machine',and 'Disconnected from virtual machine', but does not suppress the normal Pick processes messages, like the Pick logon message.

-pprinter
Parallel Printer. This option specifies that the port is to be used as a printer on a parallel device. This option must be used on Unix implementations where the device is a write-only device, such as in the case of AIX. If the parallel printer is a Read/Write device, this option is equivalent to "-printer".

-spooler
-scheduler
-phantom
Any of these three options specifies that the port is to be used as a phantom, or as a process not attached to a physical port.

-u /ttelnet.port,s
Starts AP telnet on telnet port telnet.port. This option starts the AP telnet server on the telnet port number specified by telnet.port and waits for connection from a client. The client makes the connection by using telnet on the server host and the same telnet.port.
Syntax ap {{-[0|a bootarg|port.number|f|q|k] }{-n configfile} {-t tty} {-y sttyarg} {-d dataarg} {-l} {-i nice} {-[printer|pprinter]}} {-D} {-s} {-W} {-u /ttelnet.port,s}
Options
Example
ap -0
Starts the virtual machine 'pick0' (default name).

ap -n mymachine -0
Starts the virtual machine 'mymachine'. 

ap
Starts a User process on the virtual machine 'pick0' (default name 
' '), on the first available port. (default PIB ' '). 

ap -5
Starts a User process on the virtual machine 'pick0' (default name 
'-'), on port 5. 

pick -n mymachine -7

Starts a User process on the virtual machine 'mymachine', on port 7. 

ap -q
Displays information about the virtual machine 'pick0' (default 
name). 

ap -0 -t tty2
Starts the virtual machine 0 on /dev/tty2. This statement is normally included 
in the /etc/inittab file. 

ap -3 -t tty6 -y "9600 parenb -parodd" -printer

Starts a user process on /dev/tty6 as a printer. It changes the baud rate to 
9600 baud and sets the parity to odd. This statement is normally included in 
the /etc/inittab file. 

ap -a a3x
Automatically boots the virtual machine, then does an ABS restore from device 
3, then issues an "x" option. 

ap -d 'rmdmracctrterm ibm3151rmenur'
Starts a user process on the first available port, stacking commands to wait 
until multiuser mode is entered, and then log it as "dm" on the 
account acct, executing the "term ibm3151" and "menu" 
commands. Note the first 'r' to make sure the process will be logged 
on properly the very first time after a boot.

Shell script 'boot.ap':
001 # Test if VM is active. else boot it
002 ap -q > /dev/null
003 if [ $? ! -eq 0 ]
004 then
005    -a x
006 fi

This shell script uses the -q option to test whether the virtual machine is 
booted or not. If the 'ap -q' command returns a null exit code (ok), 
then the virtual machine is already booted and nothing is done. Else the 
virtual machine is booted automatically.

$su 
password:(enter 'root' password)
$ap -l

Enters the Pick virtual machine, retaining the current Unix user id (root, 
because of 'su').

$ap -7 -u /t2007,s &

Starts a background AP telnet server process which connects to the default AP 
virtual machine "pick0" on PIB 5 and waits for connection from 
client.  If the server host name is serverhost,  a Unix client makes the 
connection by using the "telnet serverhost 2005" command in Unix 
shell.
Purpose
Related port.number
unix.pick0
tcl.pick
tcl.kill
pid
tcl.psr
virtual.machine
tcl.maxusers

updte.processor

Command updte.processor Definition/Update Processor
Applicable release versions: AP
Category Update Processor (113)
Description a dictionary-driven, full-screen editor and data processor.

UP can be used to view, create and manipulate items in files. 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 in conjunction with the Output processor (OP), UP operates as a document processor.

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.

B-tree indexes permit cruising from item to item on an attribute value sequence and from value to value in a remote file. See "index, remote" and "index, local".

Pick/BASIC subroutines can be called from attribute-defining items and file-defining items allowing absolute control of all data entry using the Update processor and dictionaries.

When evoked, UP copies the specified item to a workspace and displays as much of the item on the screen as it can. (In most applications, each input "screen" fits within a real screen.)

Any unprintable characters embedded within the item are displayed as a dot "." on AP 6.1.0 and up.

Control keys are used to perform editing functions, but as long as the control key is not pressed, all characters are entered as typed.

An optional spelling checker beeps and rejects input if a character is typed that does not lead to a legal word. See "spelling checker".

UP commands begin with a control character formed by simultaneously pressing the "<ctrl>" ("control") key and one or more alpha keys. Some UP commands require more command characters, while others require text input. The second UP command can be entered as straight alpha or with "<ctrl>" depressed. On some terminals a "<ctrl>+s" leaves the terminal locked. To unlock the terminal, type "<ctrl>+q". See "commands, up".

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 is not changed.

Without any attribute-defining items specified, UP functions as a full-screen editor.

Value marks are indicated by line breaks with no attribute label.
Syntax
Options i Include item-id in UP workspace.

l Look only. The item cannot be filed or deleted.

r Raw option. Display non-printable characters as periods. The escape character is displayed as a "[". The subvalue mark is displayed as a "" character.

s Toggle off the spelling checker.
Example
Purpose
Related tcl.update
attribute-name
tcl.spelling.checker
conversion
dictionaries.as.operators
up.a
up.sc.aa
up.sc.aaa
up.b
up.c
up.cc
up.cd
up.cl
up.cp
up.cr
up.cw
up.d
up.e
up.f
up.g
up.h
up.i
up.j
up.k
up.l
up.m
up.n
up.o
up.v
up.w
up.x
up.x0
up.x1
up.x2
up.x3
up.x4
up.x5
up.x6
up.x7
up.x8
up.x9
up.xb
up.xc
up.xe
up.xf
up.xi
up.xk
up.xl
up.xn
up.xo
up.xp
up.xr
up.xs
up.xx
up.y
up.z
up.za
up.zb
up.zc
up.zd
up.ze
up.zg
up.zh
up.zl
up.zn
up.zo
up.zp
up.zq
up.zr
up.zs
up.zt
up.zw
up.zz
up.znumber
up.overtype.mode
up.only
up.search.replace
zooming
tcl.config
up.data-entry
access.id-prompt
up.input-conversion.fdi
double.clutching
up.exit.item
basic.debugger.edit
up.delete.text
up.cursor.movement
tcl.ed
pc.value.limit
up
up.zx
tcl.view

tcl.set-port

Command tcl.set-port Verb: Access/TCL
Applicable release versions: AP, R83
Category TCL (746)
Description displays or changes the communication speed and protocol for a given port or displays the current setting if none of the communication paremeters are given.

set-port with tty format is for AP/Unix.

set-port with port.number format is for AP/DOS,Native.

"port.number" is the serial port number to change. The current port may be specified by specifying port "-1".

"baud" is the baud rate. Legal baud rates are: 110, 150, 300, 600, 1200, 2400, 4800, 9600, and 19200.

"parity" is "n" or "0" (zero) for no parity. "o" or "1" for odd parity. "e" or "2" for even parity. "m" for mark parity. "s" for space parity. ("s" and "m" parity are NOT supported in R83.)

"stop.bit" is the number of stop bits. Valid numbers are 1 or 2.

"word.length" is the data length. Valid numbers are 7 or 8.

If no options are entered, the current port settings are displayed. If any option is entered, then all options must be entered.

AP/Unix Systems:

The port can be specified either by its serial port.number, or by a device name (e.g., /dev/tty03), in which case the port does not have to be connected to the Pick virtual machine. /dev/ can be omitted. This command is provided for compatibility with non-Unix implementations.

If no Unix process is connected to the device, "set-port" displays:

Process not connected

In this case, the device is probably not initialized properly or not connected to a physical terminal.

"status-port" is a synonym of "set-port"
Syntax set-port tty{,baud,parity,stop.bits,word.length}

set-port port.number{,baud,parity, stop.bits,word.length}
Options
Example
Purpose
Related tcl.status-port
tcl.wheres
tcl.set-baud
tcl.reset-port
port.number
tcl.list-ports
system.privileges
tcl.setport
tcl.setup.sio
tcl.list-lines
tcl.set.port

basic.%connect

Command basic.%connect C Function/BASIC Program
Applicable release versions: AP/Unix
Category BASIC Program (486)
Description requests a connection between two sockets.

To compile successfully, the statement 'cfunction socket.builtin' must be included in the source code.

'socket' Is the file descriptor of the local socket returned by a previous call to the Pick/BASIC C function '%socket'.

'addr.family' Specifies the addressing scheme used by the protocol. This field must match the address family used when creating the socket. Valid values are defined in the include: 'dm,bp,unix.h socket.h'.

'host' Destination host name. This string must be known to the local network manager (normally defined in the '/etc/hosts/ Unix file). Internally, this string calls the BSD function 'gethostbyname' to read the '/etc/hosts' file.

'port' Port number on the distant host. Legal value for this field depends on the protocol. On TCP/IP, for example, valid port numbers are from 1024 to 32767.

Upon successful completion, a value of 0 is returned in 'code'. In case of error, a value of -1 is returned and the function 'system(0)' is set to the value of 'errno'.

The connection is closed when the socket is closed.
Syntax code=%connect( socket, addr.family, host, port )
Options
Example
cfunction socket.builtin
include dm,bp,unix.h socket.h

* Create a socket
fd=%socket(AF$INET,SOCKET$STREAM,0)

* Connect to the distant host        
if %connect(fd,AF$INET,"prod",1024)<0 then
  crt 'Connect failed'; stop
end

* Write data to it
msg="CONNECTED"
%write(fd,msg,len(msg))

* Terminate connection
%close(fd)
Purpose
Related basic.cfunction
basic.%socket
basic.%close

internal.format

Command internal.format Definition/General
Applicable release versions: AP, R83
Category General (155)
Description describes data that has been "internally converted" using one of the "conversion" or "processing" codes provided with Pick. As a general rule, "internal format" means the way the data is stored inside the system.

The main advantage of an "internal" format is that it takes much less time to compare two values.

For instance, time values are not stored as the human readable form. Rather, they are converted using the "mt" input processing code, which takes a legal "external" time such as "14:00" (2:00 p.m.) and calculates the number of seconds past midnight for this value, which would be the "internal" value. In this case, the "internal" form would be "50400". The same "mt" code used as an output processing code may be used to convert the internal value to its "external" form.

Dates are also more easily manipulated if stored in an "internal" format. A input processing code of "d" will take an external date, use a calculation to determine the number of days that have elapsed since December 31st, 1967 (day 0 (zero) on the Pick calendar), and store an "internal" julian date. A similar output processing code will convert an "internal" date to its human-readable "external" form. See the date processing codes for the various output formats available.

In addition, numerical values are more easily handled by the system if they are all stored as integer amounts, and the decimal point (if any) is inserted only upon output. Typical American dollar amounts, say, "$100.00" is converted upon input to an "internal" form of "10000" using the "MR2" input processing code. A similar output processing code will re-display the figure as "100.00". See the "m" processing codes for all its variations.

One final reason for using an "internal" format is to save storage space. Such an example would be to convert the external form of "SMALL", "MEDIUM", and "LARGE" into "S", "M", and "L". The internal values can them be re-constituted upon output.
Syntax
Options
Example
Purpose
Related pc.mt
external.format
pc.d
pc

basic.%bind

Command basic.%bind C Function/BASIC Program
Applicable release versions: AP/Unix
Category BASIC Program (486)
Description binds a socket to a named resource. In case of a network, the resource would be an access point into the system (see the example below).

To compile successfully, the statement 'cfunction socket.builtin' must be included in the source code.

'socket' Is the file descriptor of the local socket returned by a previous call to the Pick/BASIC C function '%socket'.

'addr.family' Specifies the addressing scheme used by the protocol. This field must match the address family used when creating the socket. Valid values are defined in the include: 'dm,bp,unix.h socket.h'.

'address' Legal values are defined in the include: 'dm,bp,unix.h socket.h'.

'port' Port number on the local host. The legal value for this field depends on the protocol. On TCP/IP, for example, valid port number are from 1024 to 32767. This field may not be applicable for all protocols.

Upon successful completion, a value of 0 is returned in 'code'. In case of an error, a value of -1 is returned and the (Pick/BASIC) function 'SYSTEM(0)' is set to the value of 'errno'.
Syntax code=%bind( socket, addr.family, address, port )
Options
Example
cfunction socket.builtin
include dm,bp,unix.h socket.h

* Create a socket
fd=%socket( AF$INET, SOCKET$STREAM, 0 )

* Bind the socket to a local Ethernet port.
* Use default address.
if %bind( fd, AF$INET, INADDR$ANY, 1024 )<0 then
  crt 'bind failed'; stop
end

* Wait for incoming connection
%listen( fd, 1 )

* Accept a connectionn
addr=0; port=0
fd=%accept( socket, &addr, &port )

* Read data from the data link
%read( fd, buffer, 1024 )
Purpose
Related basic.%listen
basic.%gethostid
basic.%socket
basic.%accept
basic.%read

legal

Command legal Introductory/Access: Modifiers
Applicable release versions:
Category Access: Modifiers (8)
Description Copyright (c) 1993, 1994, 1995 by Pick Systems. All rights reserved. This book is protected by U.S copyright law and international treaties. Unauthorized reproduction or distribution of this book, or any portion of this book, is illegal and punishable to the fullest extent of the law.

While every precaution has been taken in the preparation of this publication, the information in this manual is subject to change without notice and should not be construed as a commitment by Pick Systems. The company assumes no liability for any errors or omissions in this manual.

TRADEMARK CREDITS

Advanced Pick (r) is a registered trademark of Pick Systems.

The Pick Operating System (r) is a registered trademark of Pick Systems.

The Pick System (r) is a registered trademark of Pick Systems.

FlashBASIC is a trademark of Pick Systems.

Pick/BASIC is a trademark of Pick Systems.

Access is a trademark of Pick Systems.

Update Processor is a trademark of Pick Systems.

Output Processor is a trademark of Pick Systems.

AIX and RISC System/6000 are trademarks of International Business Machines Corporation.

DG/UX is a trademark of Data General Corporation.

MS-DOS is a trademark of the Microsoft Corporation.

SCO (r) is a registered trademark of The Santa Cruz Operation, Inc.

UNIX (r) is a registered trademark of Unix System Laboaratories.

PRINTING HISTORY

The body of this document was created using the Update and Output processors and the Pick/BASIC capabilities of Advanced Pick.
First Edition, October, 1992
Second Edition (Version 1.0.4), July, 1993
Third Edition, December, 1993
Fourth Edition (Version 2.0), January 1995

COMMENTS

Comments may be sent to the publisher:
Pick Systems
1691 Browning Avenue
Irvine, CA 92714
Syntax
Options
Example
Purpose
Related

sdb

Command sdb Definition/Unix
Applicable release versions:
Category Unix (24)
Description tool for recovery in case of a system crash, following, for instance, a power failure.

The Monitor Debugger allows:

- Display and change Pick virtual memory.
- Display and change 'real' memory (remember that 'real' memory is, in fact, Unix virtual memory).
- Force a flush of the Pick memory space back to disk.
- Display, change the status of the system semaphores, to remove a dead lock situation.
- Get access to a locked system.
- Terminate processes, including doing a shutdown.
- Trace modifications to a memory area.
- Put low level break points in the virtual code.

IMPORTANT

When the Monitor Debugger is entered unexpectedly, try first to type g<return> to see if the system restarts. If not, hit the <BREAK> key again to examine the problem. There are cases when the debugger is entered wrongfully. For instance, when some specially long, un-breakable, tape operations (like a rewind) are running, hitting the break key several times on line 0 may enter the Monitor Debugger with a 'tight loop' condition, which means the process was engaged in a 'long' operation, preventing it from servicing the <BREAK> key.

Entering the Debugger

The debugger can be entered:

- Voluntarily, by hitting the <BREAK> key on a Pick process which has been started with the -D option, to enable the Monitor Debugger.
- Voluntarily, by setting a monitor trace on real or virtual memory.
- Voluntarily, by setting a monitor break point in virtual memory.
- Following a system abort. When a serious system abort occurs, the debugger is entered. The user cannot continue from such a condition.
- Following a Monitor HALT. When a process cannot continue execution, a HALT is executed on this process. This normally does not affect the other processes. The faulty process enters the Monitor debugger and waits. Type 'x' to display the hardware registers, note them to transmit them to Technical Support and type 'g' to try restarting the process. If the process aborts again, try a logoff and/or reset-user from another terminal before trying 'g'. If it fails again, type 'q'.
- By hitting the <BREAK> key 5 times in less than 5 or 6 seconds on the line 0 when the system does not respond (system stuck in a tight loop, in a semaphore dead lock or line 0 comatized). When a semaphore is left hanging, or when the processor enters a short tight loop, due to an ABS corruption, for example, the process does not respond any more and is incapable of going to the Virtual Debugger. The fifth time the <BREAK> key is pressed, the signal handler checks to see if the first occurrence of the break was serviced normally. If it is not, the debugger is entered. On a busy system, it might be necessary to try the <BREAK> sequence several times to get to the Monitor Debugger.
- By hitting the <BREAK> key on the line 0 when it waits for a system lock (overflow lock, spooler lock, etc...) for more than approximately 5 seconds.

The different causes of entry in the debugger are displayed by a message on entry and a special prompt, as defined in the table below:

CONDITION MESSAGE PROMPT

Break key on line
started with -D <BRK> B!
System abort <ABT> A!
Monitor trace <TRC> addr C!
Break point <BPT> bp# I! Monitor HALT <HLT> code H!
Break key on line 0
on tight loop <TLP> T!
Break key on line 0
on virtual lock <VLK> V!

Referencing Data

Data can be referenced from the Monitor Debugger either in the virtual space or in the real memory space.

Data Specifications

Data location is defined by the following format:
address{;window}

The data is always displayed in hexadecimal.

Virtual Address Specification

The address of a virtual element can be represented by:
[r reg|{.}fid][.|,]disp

The base FID is either the content of the register reg or a FID number fid in decimal or in hexadecimal, prefixed by a dot. The displacement is either expressed in decimal, prefixed by a comma, or in hexadecimal, prefixed by a dot.

For example:


1.300 Offset x'300' in frame 1.
.12,16 Offset 16 in frame x'12'.
r3.100 Offset x'100' off the location pointer at by register 3.


Monitor Address Specification

The address of a Monitor element can be represented by either of the two following forms:

{ [l|g] }.hexaddress{ [+|-] {.}offset}
/symbol{ [+|-] {.}offset}

The l prefix is used for local data. The g is used for global data.

The second form requires the presence of the file sdb.sym on the current directory or on /usr/lib/pick. This file is normally not shipped with the system. It is reserved for development purpose.

The optional offset which is added to, or subtracted from, the n base address is either expressed in decimal, or in hexadecimal if prefixed by a dot.

For example:

.40000100 Absolute address.
l.0 First address in the local data space.
g.100+.10 Offset x'10' off the address x'100' in global data space.
/sys.time Address of symbol sys.time.
/tcb0+.100 Offset +x'100' off the symbol tcb0.


Window Specification

The window specifies the number of bytes to display. The window is expressed in decimal or in hexadecimal, prefixed by a dot. The default window size is 4. When using a symbolic name, the window is set automatically.

Changing Data

When a window of data is displayed, it is followed by an equal sign = . Hitting Ctrl-N will display the next window, if available, and Ctrl-P the previous one. New data can then be entered as follows:


'char Character Insertion. A character string is preceded by a single quote. The characters in the display window are replaced by those in the input string, beginning from the left.

.hex Hexadecimal string insertion. A hexadecimal string is preceded by a dot. It must contain only hexadecimal characters and an even number of nibbles. The characters in the display window are replaced by those in the input string, beginning from the left.

{+|-}int Integer. The display window is treated as a numeric element. The window must be 1, 2 or 4 byte long. The new integer replaces all data in the window.


Debugger Commands

The debugger prompts for a command with a one character code followed by an exclamation mark (!). Commands are terminated by a carriage return.


!shell Submit a Shell command. The command is submitted to shell.

? Display help information. The Unix file /usr/lib/pick/sdb.help is displayed using pg.

ba{.}fid[.|,]disp
bao{.}offset
ba+{.}offset
b{n} Add a break point. The effective address can be specified in different ways:

Form 1: The effective address is computed by adding the argument fid to the fid break point offset, and disp to the displacement break point offset defined by the bo command.

Form 2: The effective address is specified by the the fid be defined by in break point offset and offset added to the break point offset displacement set by the bo command.

Form 3: The effective address is defined by the current value of R1 to which the offset offset is added.

Form 4: The effective address is defined by the current value of R1 to which the n * 4 is added. If n is not specified, 1 is assumed. This form is used for architectures which have a fixed 4 byte instruction size (RISC).

The address must be at a virtual address boundary. Break points are global for the whole virtual machine. Once the break point is set, any process which hits it will stop. Break points are removed once they are encountered. A break point should not be set into an ABS frame which has been write required (mloaded into). Up to three break points can be set simultaneously. Upon successful setting, a '+' is displayed and the break point is displayed. Break points remain in action until they are explicitly removed or until the virtual machine is shut down.

bd[*|n] Delete break points. If * is used, all breakpoints are removed. If n from 0 to 2 is used, the specified break point is deleted.

bl List break points. List the Monitor break points.

bo{.}fid[.|,]disp Break point offset. Define a fid and displacement which are used in computing the effective address of a break point in the ba command.

d? Show/Change default dump string. In case of system abort (bus error, segmentation violation, ...), the system automatically dumps some critical elements in the file "/usr/tmp/ap.core". This file can be examined with the apcrash utility. After the display, the string can be changed by typing the new dump string after the '=' sign. The dump string can have up to 15 characters, one-character codes and arguments. See the Monitor Debugger command d below for the description of each code. The dump string can be different for each process. See the Advanced Pick Reference Manual documentation for the description of 'apcrash'.

dcommand.string Dump Pick core memory to the Unix file /usr/tmp/ap.core. The result of the dump can be examined with the utility apcrash. This command can be used, after an incident, to dump selected elements of the current Pick memory to be able to investigate the problem. See the Advanced Pick Reference Manual documentation for the description of 'apcrash'. The Unix file can be dumped to tape using Unix utility like tar (eg. tar cv /usr/tmp/ap.core). The content of the dump is controlled by command.string which is composed of one character codes, some followed by arguments. Codes can be separated by commas for readability. The order of the codes in command.string is unimportant. This dump utility is automatically invoked in case of system abort (bus error, segmentation violation, etc...) before entering the Monitor debugger. What is dumped in this case is controlled by a default dump string (see the Monitor Debugger command d? above). Valid codes are:

a : Dump 'all'. This option is equivalent to the command string "l,g,b,p,r,c,0,f1". See the description of each code below.

0 : Dump the PCB of the current process. If the PCB is not attached at this point, this performs no operation.

b : Dump the buffer table.

c : Dump the current process context. All the frames currently attached to the process, their forward and backward links are dumped.

f{.}n : Dump the fid n. If the specified frame is not in memory, it is read from disk.

g : Dump the global space.

l : Dump the local (private) memory, not including the stack.

p : Dump the pibs.

r : Dump the hardware registers. The registers are dumped in the same order as described in the Monitor debugger 'x' command described later in this appendix.

s{.}start;[*|{.}size] : Dump the main shared memory segment. Start is the starting offset, expressed in bytes and size is the size expressed in KILOBYTES. If * is used instead of size, the entire shared memory segment, starting at the specified offset, is dumped.

v{.}n : Dump n virtual buffers.
e Toggle the debugger ON/OFF. When OFF, prevent the entry to the debugger with the <BREAK> key. On line 0, though, the debugger will be entered in some special cases (See section 'Entering the Debugger' above) even when the debugger is disabled.

f{!} : Flush memory. All frames modified in memory are written back to disk. If a disk error occurs, a minus sign is displayed. If the '!' option is specified,all frames in memory, even if they are not write required, are written to disk.

g {fid.disp} : Go. Without any argument, the process resumes execution. If fid.disp is specified, control is transferred to the specified mode. fid is expressed as a relative offset in the current abs.

gl{-} : This command displays or removes group locks. With no options, the monitor prints the status of the global group lock (with a "G+" or a "G-"), and scans memory for any frames which are marked as locked. For each locked frame, the monitor displays the fid, the address of the buffer table entry, and all group lock information held in the frame itself. To clear all group locks, type "gl-". To clear a specific group lock, type "gl-{fid}". Note that locks cleared from the monitor debugger may still display with the "list-locks" command. Such locks should be cleared with a "clear-locks" command when the virtual machine becomes accessable. In general, group locks should always be cleared by TCL commands only. The monitor debugger should only be used when system access is denied due to a lock set on a critical file (like the "mds,," file).

h fid : Hash Fid. This command displays internal information about the specified FID if it is in memory, or the message <NIM> if the fid is not in memory. The content of the buffer table can be altered. Input is terminated by:

carriage return : return to debugger.
^N : Next buffer table entry, following the age queue forward link.
^P : Previous buffer table entry, following the age queue backward link.
^F : Next buffer table entry, following the hash queue forward link.

k{w}[f| pib ] : Kill. Terminate the process associated to the PIB pib or the flusher if used with the key f by sending a SIGTERM to it. The w key waits up to 10 seconds for the process to terminate. If it does not terminate, a SIGKILL is sent to it. Note that if the target process is in the Monitor Debugger or stuck on a semaphore, the SIGTERM signal will have no effect until it leaves the Monitor debugger or the semaphore is released. Kill the flusher ('k{w}f') will unconditionally log all processes off and shut down the virtual machine.

l fid : Display/Modify Link fields. Displays in hexadecimal the link fields of the frame fid, in the following format:

nncf:frmn:frmp:npcf:clnk=

nncf: number of next contiguous frame(s)
frmn: forward link
frmp: backward link
npcf: number of prior contiguous frame(s)
clnk: core link

New values for the fields can then be entered, separated by commas, with an empty field to leave a field untouched.

m {*}monitor.address{;window} : Display/Change Real Memory. Display the specified window at the real address as specified (see the section about Monitor address specification above in this section). If an asterisk (*) is used, the address is considered as a pointer and its content is used as the monitor address. The length and window specification applies to the area pointed at by the pointer.

IMPORTANT: Access to an illegal address will cause a segmentation violation or a bus error sending control back to the Monitor Debugger with an abort condition, from which it is impossible to recover. It is strongly advised to avoid absolute addresses, since they vary from implementation to implementation.

p {pib}{[.|,]offset}{;window} Display/Change PIB. Display window bytes in the pib specified by pib (current pib if pib is omitted), at the optional offset offset.

q{!} : Quit. Quit Monitor debugger. Confirmation is asked. Leaving the Monitor Debugger terminates the Pick process. When asked to confirm, the user must type y (no return). The optional '!' by-passes the normal Pick termination, and terminates the process abruptly. This forms should be used only in extreme situations where even quitting from the Monitor Debugger aborts.

r reg{.disp}{;window} : Display data through register. Displays data pointed at by the register reg from 0 through 15. If specified, disp is added to the register displacement.

c [*|sem]{[?|+|-]} Display/Change semaphore status. Display or change the semaphore specified by sem, expressed from 1 through 3, or all semaphores if the key * is used. The key + sets (locks) the specified semaphore. The key - resets (unlock) the specified semaphore. The key ? displays the information as in the example below:

00: O pid=0985
01: O pib=0023 W
02:
03: O pib=001A

where semaphore 0 is owned by the process with the pid number of x'0985' - Only semaphore 0 is displayed with the Unix pid number instead of the Pick pib number; semaphore 1 is busy, owned by the pib x'23' and has at least one process waiting on it (W); semaphore 2 is free; semaphore 3 is busy, owned by process x'1A' but has no process waiting on it. If the owner pib is not setup yet when the command was executed, the "pib=?" is displayed. Re-enter the command again to see to owner pib.

S{f}{h}{i}{m}{s}{w}{-} Scan buffer table bits. This command displays and/or clears buffer table bits depending upon certain criteria. The options are as follows:

f Referenced bit
h Hold bit
i iobusy bit (disk read)
m Temporary mlock bit
s Suppress detail output. Show only total.
w Write-required bit
- Clear instead of display

The user specifies which bits to search for using the above options. When a buffer is found, it is displayed in a manner similar to that of the "h" command. The user may go backwards or forwards in the selection list with the CTL-P and CTL-N commands. At the completion, the total count of items is indicated. Note that the count is only accurate if forward movement only is used.

t{[mmonitor.address|fid.disp]{;window}} Set/remove Monitor trace. Without any argument, any pending monitor trace is removed. A minus sign is displayed in acknowledgment of the removal. Else, set a trace on the specified area of memory starting at monitor.address or the area of memory associated to fid.disp with a length equal to window. If no window is specified, the default window or the size of the monitor element is used. The maximum window size on a monitor address is 32767. The maximum window on a virtual address is the frame size. A plus sign is displayed in acknowledgment of the setting. The memory is checked for any change at every virtual branch or call, and every frame fault. If the memory is changed, the Monitor debugger is entered. When setting a trace on a virtual address, the frame is locked in memory. Removing the trace unlocks the frame if it was not locked when the trace was set.

v{code} Enter the Virtual Debugger with a code 'code'. If 'code' is not specified, it just enter the debugger as if the <BREAK> key had been hit. 'code=14' will log off the process. This command will display 'ADDR' and fail if the Virtual Debugger PCB is not set up.

x Display hardware registers. Display on the first line the program counter, followed by a variable number of 32 bit registers. The information is implementation dependant:


AIX: Registers r3 through r31.
SCO: Registers edi esi ebp esp ebx edx ecx eax
HP-UX: Registers r2 through r30
SINIX (MIPS): Registers r1 through r30
SVS (ICL DRS6000): Registers %pc %npc %g1 %o %l %i


y{!} Toggle Lock By-Pass. When ON, the process under debugger will by-pass all locks in the system, monitor and virtual. This option should be used very carefully, since it can create extensive damage if used on a live system. To be used safely, all other processes should be either logged off or stopped by setting a semaphore (see section 'Usage Hints' below). Unless used with the key !, the user has to confirm the activation of this by-pass.


Usage Hints

This section shows how to use the Monitor Debugger to perform some unusual actions. Extreme care must be exercised when using the debugger to remove a lock or a semaphore. This may cause data loss. It is strongly recommended to contact Technical Support when a system gets locked.


- Running in single user. To prevent all users from running, except one terminal:

At shell, activate a Pick process in the Debugger.
ap -D <return>
Once in the Monitor Debugger:
B! s1+ <return>
B! y <return> and confirm by typing 'y'
B! g <return>

All processes will now be locked, except the one running under the debugger and the flusher. This is useful when patching some critical virtual structures, like the Overflow table.

To restart the multiuser activity:

Break into the Monitor Debugger (either on the line which has the lock set, or on line 0 by hitting <BREAK> twice, since the line 0 should be locked by the semaphore).

This enters the Monitor Debugger.
B! y <return> to toggle the by-pass off
B! s1- <return>
B! g <return>

All processes will now be unlocked.

- Removing a dead lock. When a process has been killed by the system, it may have left a semaphore or a virtual lock behind. To remove the lock, make sure all users are inactive, and do the following:

On the line 0, hit <BREAK> up to six times, in less than 5 or 6 seconds. The process should drop into the Monitor Debugger, with the message <TLP> in case of a tight loop, or <VLK> in case of a virtual lock. Do the following, depending on the case:

T! f <return>
T! s*? <return>
Note which semaphore number is set and remove it by the command:
T! s semnum - <return>
T! g <return>

If the lock is a virtual lock, it may have to be cleared. This may have disastrous results if done without some inside information. It is strongly advised to contact technical support.
V! f <return>
V! r15;2 <return>
The system will display a number. If non zero, zero it. Else, there is another problem. Contact technical support.
V! r15;2 .001A= 0 <return>
V! g <return>


A virtual lock might also be one of the system wide locks. Do the following to identify it:
V! f <return>
V! 1.100;2 <return>
The system will display a number, normally 0. Type <ctrl> N 10 times or until a non zero value shows. If no null value shows, there may be another problem. Contact technical support.
V! 1.100 .0000= Ctrl N
V! 1.102 .001A= 0 <return>
V! g <return>


A virtual lock might also be an item lock (6.1 and above only). Do the following to identify it:
V! 1.15a;6 <return> <return>
The system should display a frame number. Now type the following:
V! .(frame number displayed before).0;4 <return>
The system displays an 8 digit hex number. The first 4 digits indicate the global lock, while the next 4 digits indicate the number of item locks. To zero both of these, type "0" at the "=" prompt followed by a <return>.


A virtual lock might also be a group lock (6.1 and above only). Do the following to identify it:
V! gl <return>
If the system prints anything other than "G-" then group locks are set. To clear them, type the following:
V! gl- <return>
V! gl <return>
The system should report "G-" after the last command. Note that the virtual machine may still report locks set if the "list-locks" command is used. To fix this, go back to tcl as follows:
V! g <return>
If the system does not go to a tcl prompt, then some other lock condition exists and the user should contact technical support. If a tcl prompt appears, type the following:
: clear-locks (g <return>
Allow some time for "clear-locks" to complete as it can be delayed by processes which have been terminated abnormally. After completion, the group locks should be cleared. If any further deadlocks are encountered, contact technical support.


If only the line 0 is stuck, it might be because it has been accidentally comatized. The WHERE command shows the first two characters of the status field as FE or 7E. A logoff from another port will un-comatize the line 0, or do the following:
T! p.0;1 <return>
T! p.0;1 .7E= .ff <return>
T! g <return>


- Enabling the debugger on line 0. If the line 0 has been started without the -D option, it is impossible to get in the Monitor debugger, unless there is a lock. To enable the debugger, proceed as follows, to set temporarily a virtual lock to be able to drop in the debugger, enable it and restart:
At TCL:
: debug <return>
! 1.102;2 <return>
! 1.102;2= -1 <return> This sets the overflow lock
! g <return>.
Line 0 (and the WHOLE system) is now locked. Wait 5 seconds and hit the <BREAK> key. This drops in the debugger.
V! 1.102;2 <return>
V! 1.102;2 .FFFF= 0 <return>
V! e <return>
V! g <return>
The Monitor Debugger is now enabled on line 0.


- Finding your line number. To determine the PIB number on which the debugger is running, do the following:
Break into the debugger.
B! p.18;2 <return>
This displays in hexadecimal the pib number +1


- Restarting the virtual machine after an abort early in the boot stage. If the virtual machine boot aborts very early (during or right after the 'Diagnostic' message), after having corrected the error when possible, the Boot can be restarted quickly by doing (the line 0 must have been started with the '-D' option):
! Hit the <BREAK> key to enter the Monitor debugger
B! g3.0 <return>
This should redisplay the message 'Diagnostic ...' and proceed.

Precautions

A process started with the -D option has some special privileges, which might lead to data destruction if used indiscriminately:

- Access to the virtual machine will always be granted, even if the Initialization lock is set. In particular, it would be possible to start a user process while the line 0 is in the process of initializing the virtual machine. Therefore, always make sure that the line 0 has reached, at least, the 'Diagnostics...' stage before starting a process.

- A process with debugger privilege may by-pass all locks, including virtual locks! When changing data structures, be sure that nobody is accessing the virtual machine, or, better, set a semaphore, as shown above, to prevent concurrent access. For the same reason, use debugger only on one line at a time.

- When the memory is full, the debugger can abort with the message 'MEM FULL'. Do a flush and retry until it succeeds.

- When the system runs in 'single user' (with a lock set by the command s1+) and with the lock by-pass activated, do not try to shut down the system with the TCL command shutdown. Instead, go to the monitor debugger, do a flush (f) and kill the flush process (kf). This terminates all active processes.

- When changing virtual memory with the debugger, it is a good idea to flush memory frequently, using the f command.
Syntax
Options
Example
Purpose
Related

runoff.read

Command runoff.read Command/Runoff: Commands
Applicable release versions: AP, R83
Category Runoff: Commands (93)
Description transfers control to the specified Runoff item for output and returns control upon completion.

This command causes Runoff to read the "item-id" indicated. If no "file.reference" is given, the item is read from the same file as the item being processed.

The text input from this item is processed and output without any parameter or mode changes. After processing this item, Runoff resumes input with the next line of the current source of input.

This command does not cause a "break".

The ".read" command scans the string following the command, looking for an "item-id" or a file name. The legal delimiter for the "item-id" or "file.reference" is a blank or a period.

If there is more than one blank-delimited field following the ".read" command, the next-to-the-last field is taken to be the file name, and that file is opened. The last field delimited with a blank is considered the "item-id", and it is retrieved by the Runoff processor to be executed next.

If the statement is a ".read", the processor eventually returns to the current item and continues processing at the beginning of the next line in the item. No statements which occur after the ".read" statement in the line are executed.

A comment statement may be included after the ".read". The line is considered exhausted when the processor encounters an end-of-line mark, or when it encounters a period preceeded by a space.
Syntax .read {file.reference} item-id
Options
Example
Purpose
Related runoff.commands
runoff.options.c
runoff.chain

access.with

Command access.with Modifier/Access: Verbs
Applicable release versions: AP, R83
Category Access: Verbs (152)
Description marks the beginning of a selection processor conditional, which is processed against the associated file to select items to pass on to the LIST processor.

The "not" (or "no") modifier negates the normal effect of selection -- only those item that do NOT meet the criteria are selected.

"value" is a specific value to match, enclosed in double quotes (") or backslashes (). If a selection criterion does not include a value, all items that have at least one value for the specified attribute name are selected.

"every" (or "each") specifies that in a multi-valued attribute, every value for the attribute must meet the specified condition.

"attr.name" is the name of an attribute as specified by the attribute-defining item in the dictionary.

"operator" is any legal relational operator, such as "=".
Syntax with {not} {each} attr.name {operator} {"value"}
Options
Example
list entity with contact

list entity with no contact and with phone

list invoices if amount.due > "100"

list entity if no phone.number

list entity with no contact and no phone.number

list orders if every quantity.ordered > "10"
Purpose
Related access.use.of.quotes
access.if
access.logical.connectives
access.each
access.seqlist
list.processor
access.sellist
access.without
access.modifiers
list.processor
access.attr.name
access.not
access.selection.criteria
access.any

maxfid

Command maxfid Definition/General
Applicable release versions: AP, R83
Category General (155)
Description refers to the "last" addressable frame on the disk. The "what" command outputs the current "maxfid".

Any reference to a fid higher than "maxfid" results in the message, "referencing illegal frame".
Syntax
Options
Example
Purpose
Related tcl.what
fid
scrubber
boot.error

pc.d

Command pc.d Processing Code/Restore Processor
Applicable release versions: AP, AP 6.1, R83
Category Restore Processor (84)
Description invokes the date conversion function, to convert an external date to internal format, or to convert an internal date to one of many available output formats.

By convention, day "0" (in "internal" format) on the Pick calendar is December 31, 1967. It was selected in 1968 and has never been changed, thereby retaining compatibility. For example, June 26, 1987 has an internal value of 7117, which is the number of days since 12/31/67. It follows that 7118 is June 27, 1987. Dates before 1968 are stored as negative numbers. For example, December 30th, 1967 is "-1".

"yr.pos" specifies the number of display digits for the year. For example, if the internal date is 7117, "d2" returns 26 Jun 87. Valid entries are 0, 1, 2, 3, or 4. The default is 4.

The parameters specified in "skipdel" and "#skips" are functionally equivalent to the "g" (group extract) processing code. They define the position of the date value portion in a multi-part data value and for the most part, are unused.

The "outsep" (output separation character) parameter specifies the character that delimits the month, day and year values. Popular characters to use are "-", as in "12-23-1955", or "/", as in "1/16/1997".

If the "outsep" parameter is omitted, then a " " (space) is assumed.

The output order is: 2-digit day, 3-digit month abbreviation and year. The number of year digits depends on the "yr.pos" parameter (dd mmm yyyy or dd mmm yy).

The following formats can be used to input dates:

Format Description

mm/dd/yy Default - any separator may be used (e.g., 6*26*87).
mm/dd Year is same as system date.
mmdd Year is same as system date (when in "standard" format)
dd Month and year are same as system date. On releases 6.1.0 and above, it is necessary to use the "dn" variant to get this functionality. The normal "d" conversion returns null in this case for compatibility with R83.
dd/mm/yy "European" format.
dd/mm "European" format.
ddd Julian date (1-366).
yyddd Julian date (five digits).
yymmdd Military date if in US mode.
ddmmyy Military date if in European mode.

If the date processing code is used as an input-conversion in the Update processor, a period (".") may be entered to duplicate the last date entered. The "/" (slash) by itself may be used to insert the current day's date.

If the "d" processing code is specified as an input-conversion, no codes are required for input date conversion except for the Julian and European formats, since the format is obvious in all other cases. If the "n" character is added after the "d", then the user can pass the numeric day of the month, and the function returns the correct internal date assuming the current month and year (6.1 and above only).

When the date processing code is used as an output-conversion, it converts the internal date to an external format as specified by one of the following optional character codes:

The "char.code" may be any of the following:

d Numeric day of the month (1-31).

f Full external date with alphabetic month, day of the month and four-digit year (e.g., October 9, 1990).

i This is a special case used when data is stored in its internal representation. It is typically used on the correlative attribute to convert an external date to its internal equivalent in the pre-processing phase of Access. Any legal date conversion may be specified on the output-conversion attribute prior to displaying the date.

j Julian day of the year (1-366).

m Numeric month (1-12).

ma Alphabetic month (January, February, ...)

q Numeric quarter (1-4).

w Numeric day of the week (1=Monday, 2=Tuesday, 3=Wednesday, ...).

wa Alphabetic day of week (Sunday, Monday, ...).

y Year (default is 4 digits).

The date code with no parameters converts legal date formats into the internal date (number of days from 12/31/67).

When used in a BASIC program in an oconv() statement, the results may be in either all uppercase (as in R83), or in mixed Upper/lowercase. If casing is off, then the output will be in Upper/lowercase. If casing is on, then the output will be in Uppercase only.
Syntax d{n}{yr.pos}{skipdel #skips}{outsep}
d{n}{yr.pos}{char.option}{outsep}
Options
Example
data     code  sample output

10594    d     01 Jan 1997
10594    d2-   01-01-97
10594    d-    01-01-1997
10594    d0    01 Jan
10594    d0-   01-01
10594    dd    1
1/1/97   di    10594
10677    dj    84
10594    dm    1
10594    dma   January
10594    dq    1
10594    dw    3
10594    dwa   Wednesday
10594    dy    1997
10594    d2y   97
-10594   d4    29 Dec 1938
Purpose
Related basic.date
tcl.set-date-format
output-conversion
tcl.set-date-std
tcl.date.iconv
basic.conv.expression
basic.oconv
basic.iconv
processing.codes
basic.timedate
external.format
pc.date
internal.format
tcl.date
up.input-conversion.adi
ue.1193
ue.7193
compile.time.date.stamp.rp
compile.time.date.stamp.ap
pc
basic.casing

pc.o

Command pc.o Processing Code/Restore Processor
Applicable release versions: AP
Category Restore Processor (84)
Description sorts the values in the specified attribute(s) in ascending order. The values are sorted when the item is filed.

While this CAN be used in the "correlative" attribute of an attribute-defining item, it causes the screen to refresh with each value added. To prevent this from occurring, it is advised that this processing code be placed on the "correlative" attribute of the file-defining item using the format listed below.

1) Attribute-Defining Items:

Syntax: o

Where Used:
correlative: used here
input-conversion: aborts with illegal use message
output-conversion: aborts with illegal use message

Function:

After a value is entered, the screen is redisplayed with the value placed in ascending alphabetic (a-z) order.

The sort does NOT take place until a value is added to an attribute. If the processing code is added to an existing attribute, the attribute can be displayed and filed without the attribute getting sorted. If a value is added, the attribute is sorted.

2) File-Defining Items:

Syntax: o{;}attribute.number{;attribute.number...}

In file-defining items, the "o" processing code may only be used in the "correlative" attribute. The first semi-colon is optional.

Function:

When the item is filed, the values in the attribute(s) specified by "attribute.number" is/are sorted and replaced in ascending alphabetic (a-z) order.

If an attribute is not already sorted, adding this processing code sorts the attribute the next time the item is filed.
Syntax o
o{;}attribute.number{;attribute.number...}
Options
Example
Purpose
Related ue.1072
processing.codes
up.input-conversion.adi
input-conversion
conversion
output-conversion
up.output-conversion.adi
up.correlative.adi
pc.ms
pc

filename.errors

Command filename.errors Definition/Access: General
Applicable release versions: AP
Category Access: General (65)
Description contains system error messages used to determine how the system is functioning.

The errors file contains error and "log-msg" messages. See "log-msg".

The item-ids are nine-digit date-time stamps (four-digit date plus five-digit time) plus an alpha character for multiple creations within a second.

The specific types of errors which generate messages are:

1) System errors: illegal opcode, crossing frame limit, forward link zero, backward link zero, priv opcode, illegal frame reference, disk error, stack format error, overflow release error, gfe, index B-tree error.

2) "logoff" commands.

3) Errors from the TPS (test procedure suite) on the QA account.

The attributes for the "errors" file are:

ac attribute-name description...........................

0 date Date error was logged.
0 timedate Item-id in errors file consists of date
and time error was logged.
1 error Error code. Possible errors are:
01 phantom read
02 rtn full
03 zero fid
04 frm lmt
05 fwd link
06 bck link
07 priv op
08 bad fid
09 disk err
0a break
0b stk fmt
0c lvl push
0e end off
0f trace
11 gfe count
12 gfe link
13 gfe body
14 gfe hash
15 b-tree index
16 ovf mul rel
17 end
18 unused
19 logoff
1a overflow runaway
1b ovf abort
20 ovf signature error
21 ovf link error
22 fcb corruption
23 (unknown)
24 (unknown)
25 CLEAR-LOCKS performed
p tps program error
s shutdown
2 user The user of the error logging process.
3 r Register triggering the error.
4 mode-addr Mode address when the error occurred.
5 abs-fid Base fid of the abs area executed by the process.
6 pgm-ctr Program counter when the error occurred.
7 abs-date Creation date of the abs in which the error
occurred
8 abs-imp Implementation type of the abs in which the
error occurred.
11 pcb-fid Process control block (pcb) frame id.
12 userpib The user and pib of the error logging process
20 registers Process register image.
21 run-stack Process execution stack.
22 last-tcl-entry The last three tcl stack entries.
23 gfe-fid Contains four values:
1) frame id of the group with gfe,
2) address (in storage register format)
of the item in which gfe was detected,
3) forward link of the frame in which
gfe occured,
4) backward link of the same frame
24 gfe-file The path name of the file in which gfe
was found.

Disk Error
On AP/Unix, the error log for a disk error has the following format:

ee dd 0000 00 00 ffffffff xx

ee Unix error code. (value of errno)
dd Logical disk number, as defined in configuration file
ffffffff Frame number, in hex
xx Command: 00=read, 01=write

The other fields are unused. Depending on the implementation, some other information can be obtained from the Unix error log.
Syntax
Options
Example
Purpose
Related filename.system-errors
filename.er
tcl.list-system-errors
tcl.coldstart.log
tcl.list-logoffs
tcl.logoff.error
tcl.last.tcl.entry
tcl.tcl.stack.desc
tcl.log-msg
tcl.lerrs
gfe.handler
tcl.list-errors
tcl.net-errors

system.debugger.functions

Command system.debugger.functions Definition/System Debugger
Applicable release versions: AP, R83
Category System Debugger (42)
Description briefly discusses the functions and commands that are available using the replace or assignment function, "=".

Once a valid address has been specified, the debugger accesses the requested location and displays its current contents. The cursor is positioned to the right of an "=" sign, indicating that the debugger is ready to either accept any of the following special functions or change the contents of the window.

/ctr1 .0120 =

The following commands are available in response to the "=" prompt character that appears as the result of a legal debugger command:

/ctr1 .0120 =<return>

(carriage return). Returns control to the debugger command processor (!). This leaves the window unchanged.

/ctr1 .0120 =<lf> .0043 =

(linefeed). Displays the next "window" of data, on the same line.

/ctr1 .0120 =<ctrl>+n
1890.94 .0043 =

Displays the address and the contents of the next window on the next line which includes decimal frame and hex offset.

/ctr1 .0120 =<ctrl>+p
1890.90 .0020 =

Displays the address and the contents of the previous window on the next line which includes decimal frame and hex offset.

c*bmsbeg;10 employees ='string

Places the characters "string" at the beginning of the displayed window for the length of string, which may not exceed forty bytes. The string must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p.

/ctr1 .0120 =decimal number

Places the value of the decimal number in the displayed window, filling from the right, if the window is 1, 2, 4, or 6 bytes in length, and does not cross a frame boundary. The string must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p.

/ctr1 .0120 =.hexadecimal string

Places the value of the hexadecimal string in the displayed window, filling from the left. The string must contain an even number of hexadecimal characters, and may not exceed 38 hexadecimal characters. Notice the "." prefix. This distinguishes between hexadecimal and decimal entries. The string must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p.

/h0 =b<return>
1891.f:0 =<ctrl>+n
1891.f:1 ={1 or 0}

The b shows data in binary mode, 1's and 0's are the only legal values allowed to be entered and must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p. Notice the most significant bit is bit zero and least significant is bit 7 in a displayed byte.

/ctr1 .0121 =0

(zero). Clears the window to hex zeros. The string must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p. Any size window can be cleared with a single zero.

/ctr1 .0120 =a
1891.92 .0120 =

Redisplays the address and contents of the last window.

/ctr1 .4445 =c
1891.92 DE=c4
1891.92 DEFG =c.2;2
1892.94 FG =

These forms change the display type, window and offset if specified, and redisplay either the original field with the new type and/or window specification, or the resulting field if the offset is changed. The string must terminate with a <return>, <enter>, <lf>, <ctrl>+n, or <ctrl>+p. "c" is for character mode display and ";" is the window width. "c.2;2" moves the window over bytes and displays a window of 2 bytes.
Syntax
Options
Example
Purpose
Related system.debugger.r
system.debugger.drs
system.debugger.dfs
system.debugger.dws
system.debugger.m
system.debugger.muld
system.debugger.n
system.debugger.off
system.debugger.p
system.debugger.subd
system.debugger.time
system.debugger.u
system.debugger.x
system.debugger.y
system.debugger.z
basic.debugger.de
basic.debugger.debug
system.debugger.db
system.debugger.a
system.debugger.c
system.debugger.d
system.debugger.g
system.debugger.i
system.debugger.l
system.debugger.w

tcl.config.options

Command tcl.config.options Menu/TCL
Applicable release versions: AP/Unix, AP 6.0
Category TCL (746)
Description enters the Update processor to show various options of the current virtual machine or of the specified virtual machine "vmname".

"Machine name"
This text is returned by the 'which' (TCL) command and the system(100) Pick/BASIC intrinsic function, after the name of the Pick configuration file. It can be any string. The installation procedure always changes this field to a default.

"Boot mode"
This one-letter option defines whether the system comes up in single ('s') or multi-user ('m') mode. When in Multi-user mode, users are allowed to log on as soon as the system starts (right after the message 'diagnostics ... successfully completed'), during the execution of the system-coldstart procedure. When in single user mode, user logon is denied until the line 0 executes the 'maxusers (mlq' command. This command should be included at the end of the 'user-coldstart' macro, after all application-specific commands are done (starting printers, setting terminals, communications, etc...). The default is to boot in single user mode.

"Auto boot sleep"
This number specifies in seconds the grace delay allocated when doing an auto boot ('ap -a x') to stop the boot and return to a manual boot. The default is 3 seconds.

"ABS lock"
This flag, "on" or "off", controls whether the entire Pick kernel is brought in memory at boot time ('Locking ABS ...'). The installation procedure turns this flag on automatically if there is enough memory allocated to Pick. Severe performance degradation will occur if this flag is turned off. Disabling the ABS locking should be reserved for very small configurations (less than a few megabytes).

"Break char (hex)"
This is the default value of the alternate break character, coded in hexadecimal. This value can be overridden on a per-port basis by the 'set-break' TCL command.

"Escape char (hex)"
This is the default value of the escape level pushing character, coded in hexadecimal. This value can be overridden on a per port basis by the 'set-esc' TCL command.

"Priority"
This number specifies the relative priority of the Pick processes running on the virtual machine, compared to other Unix processes, by affecting the 'nice' value. Legal values are from -20 (highest priority) to +19 (lowest priority). '0' is a 'neutral' value, giving equal priority to Pick processes and non Pick processes. The flush process always run at a nice value of -10 (higher priority) than the base line.
Syntax config options {vmname}
Options
Example
Machine name      development
Boot mode         s
Auto boot sleep   5
ABS lock          on
Break char (hex)  1c
Escape char (hex) 1b
Priority          10

These options have the following effect:

- system(100) in Pick/BASIC will return the string:
    pick0:development

- The system is booted in single user mode.

- The grace delay for booting automatically is set at 5 seconds.

- The alternate break char is set to x'1c'. This key normally 
associated with <ctrl>+ (control + backslash).

- The escape level pushing is associated to x'1b', which is the 
normal escape character.
Purpose
Related tcl.which
tcl.set-esc
tcl.set-break
tcl.maxusers
basic.system
TCL.CONFIG
boot.error

screen.input

Command screen.input Subroutine/BASIC Program
Applicable release versions:
Category BASIC Program (486)
Description displays a formated screen and waits for input from a user. Multiple fields can be entered by the user before validation. Type checking is done by the subroutine, and the caller may provide a custom external routine to perform additional controls.


Input :

The COMMON variables defined in "dm,bp,includes screen.inc" must be set as follows:

screen Array of up to 512 options. If multivalued, the options are presented in a multicolumnar format, with the input field underneath the headers. Data is entered and validated when the cursor is moved out of the field by: CTRL-N: Next; CTRL-B: Back; CTRL-J: Move left; CTRL-K: Move right. CTRL-X erases an input field.

screen.data Array of data. If non null, the data is displayed and can be modified by the user.

screen.type Array of type controls. Controls user input. If the corresponding 'screen' element is multivalued, the control applies to all multivalues. See the section 'Input Control' below.

screen.help Array of help messages. The message is displayed starting at the line specified by 'screen.msgline'. A value mark is a line separator. If non null, the help is displayed starting at the line specified by 'screen.msgline' when the cursor is moved to the corresponding option.

screen.size Number of actual entries in the 'screen' array.

screen.title Title. Displayed underlined.

screen.x
screen.y Coordinates of the upper left corner of the menu, starting at 0,0.

screen.active Option number to set as 'active' (highlighted).

screen.lastline Last line available to display the menu. If there are more options than there are available lines, the menu is displayed in columnar format. If there are more columns than possible to display on the 80 columns screen, only some columns are displayed.

screen.width Width of an option. The default is 35 characters.

screen.msgline Line number where the help messages can be displayed. The message area then extends up to the end of the screen.

screen.notice If non null, contains the name of an external subroutine which is called periodically. The main program can provide a polling routine to display user information or perform some periodic task.

screen.control If non null, contains the name of an external subroutine which performs custom controls on user input. This routine must either be cataloged in the current account, or, better, be an explicit path name, like 'accounting,bp, check.input'. See the section 'Input Control Subroutine' below


Output :

The following variables are then updated:

screen.active User selection:
Q : Quit or ESC
Y : Validated

screen.maxsize Last line actually displayed on screen. In most cases, it is screen.y+screen.size, but, if there are too many options to fit in one column, this variable will reflect the actual last line on screen. This is used by screen.erase.


Input Control :

The 'screen.type' array elements contains the following codes:

<null> Optional field. May be left empty. No control.

t Required field. Any text.

x Display only. The user is not allowed to modify the data. The cursor cannot be moved into the corresponding field.

l Explicit list. The user can enter only one of an explicit list of elements. Each element is separated by a tilde. For example: 'l~yes~no~'. Note a trailing tilde is required.

y Confirmation field. The user can only select [y{es}|n{o}|q{uit}]. If 'y{es}' is entered, the routine terminate.

n Numeric field. Followed by the min and max legal values (inclusive), separated by a dash. For example: 'n0-1024'.

<number> Custom control code. This strictly positive number is passed as the first argument to the user provided external routine specified in 'screen.control'.


Input Control Subroutine :

The user can specify an external subroutine in 'screen.control' which is called when the control code in a 'screen.type' array element is a number. This number is passed as the first argument of the subroutine, along with other information. The subroutine can then either validate the subroutine, and/or modify the user input. The user must provide a subroutine with the following arguments:

Input:
1st arg: Control type number
2nd arg: User input data
3rd arg: Data field we are leaving (the one to control)
4th arg: Data field we are entering (where the cursor now is)

Output:
1st arg: Set to 0 if data is invalid, or 1 if ok.
2nd arg: Validated data, if 1st arg=1
3rd arg: Unchanged
4th arg: Unchanged
Syntax call "dm,bp, screen.input"
Options
Example
Example :

The following example displays a screen like:

User    : ...........
Order #1          Order #2
................  .................
 
include dm,bp,includes screen.inc

* Init the screen
* ---------------
call "dm,bp, screen.init"

* Clear the whole screen
* ----------------------
crt @(-1)

* Build the menu
* --------------
screen.x=0 ; screen.y=0      ;* Top left corner

screen(1)="User"             ;* Option 1
screen(2)=""
screen(2)<1,-1>="Order #1  " ;* 1st column
screen(2)<1,-1>="Order #2  " ;* 2nd column

screen.type(1)='t'           ;* Mandatory text
screen.type(2)=1             ;* User provided control

mat screen.data=''           ;* Clear result

screen.help(1)="User name"   ;* Help messages
screen.help(2)="Account number and val date"

screen.size=2                ;* Number of options
screen.active=1              ;* Option 1 is default
screen.msgline=23            ;* Help line

screen.control="account,bp, check.input"

* Display the screen and input data
* ---------------------------------
call "dm,bp, screen.input"
begin case
  case screen.active='x'
    * Back to TCL
    stop
  case screen.active='q'
    * User typed 'q' or ESC
    ....
  case screen.active='y'
    * OK. Validated
    ....
  
end case
Purpose
Related general.screen
screen.init
screen.display
screen.erase

signals

Command signals Definition/Unix
Applicable release versions: AP/Unix
Category Unix (24)
Description examines Unix signals in relationship to the Pick Virtal Machine.

This discussion is intended for experienced Unix programmers to interface Unix applications with Pick or to use Unix process synchronization in a purely Pick environment.
For performance reasons, Unix signals are not used in regular Pick activity. They are used solely to handle exceptions. Diverting signal usage for an application would simply remove nonessential facilities, like the possibility to send a message or to logoff a process. This does not mean that signals can be used freely, though. The Pick Monitor provides a system call to process regular Pick signals inside a customized signal handler, thus combining system and application signal handling.

The following list, details the Pick signal system call and gives some examples of application signal handler.

Signal Usage

The following is a table of the signals currently used by Advanced Pick. Future development may require using more signals.

Advanced Pick uses only System V.3 signals, which are common to more recent Unix versions. Non System V.3 signals are left to their default signal handler (normally SIG_IGN) as set by the system.

Numerical values may vary between Unix implementations. It is very important to use the proper include when writing in C or the include dm,bp,unix.h, signal.h when writing FlashBASIC or Pick/BASIC programs using signals.

Signal Description

SIGHUP Hangup. When received, the process is logged off Pick, but remains connected to the virtual machine. The signal is controlled by the hupcl command in the Pick configuration file. It is normally generated by the TTY device driver when data carrier is lost. This signal can be altered by the TCL command trap dcd command .

SIGINT Interrupt. Generated by the BREAK key and the alternate rtual Machine. break character as defined by the brkchr in the configuration file or by the TCL command set-break . The process is sent to the FlashBASIC, Pick/BASIC, or system debugger, if brk-debug is on or a level is pushed if brk-level is on.

SIGQUIT Quit. Generated by the ESC key or the alternate escape character as defined by the escchr in the configuration file or by the TCL command set-esc . A level is pushed if esc-level is on. If esc-data is on, a signal is still generated, but eventually ignored by the Virtual debugger. The character defined by set-esc will eventually be put in the process input buffer, but it must be emphasized that a noticeable delay can be experienced when inputting this character.

SIGILL Illegal instruction. Sends the process to the system debugger with an 'illegal opcode' abort. Used for assembly single stepping on some implementations.

SIGTRAP Trace trap. Sends the process to the system debugger with an 'illegal opcode' abort. Used for assembly single stepping on some implementations.

SIGIOT I/O trap instruction. Sends the process to the system debugger with an 'illegal opcode' abort.

SIGEMT Emulator trap. Sends the process to the system debugger with an 'illegal opcode' abort. Used for assembly single stepping on some implementations.

SIGFPE Floating point exception. Sends the process to the system debugger with an 'illegal opcode' abort.

SIGKILL Kill. This signal cannot be caught and will terminate the process immediately after doing a logoff. Killing the flusher of a virtual machine will log all processes off and shut down the virtual machine.

SIGBUS Bus error. Sends the process to the system debugger with an 'illegal opcode' abort. Used for assembly single stepping on some implementations.

SIGSEGV Segmentation violation. Sends the process to the system debugger with an 'illegal opcode' abort. Used for assembly single stepping on some implementations.

SIGSYS Bad argument to a system call. Sends the process to the system debugger with an 'illegal opcode' abort.

SIGPIPE Write to a pipe with no one to read it. The process is sent to the Virtual debugger. Pipes are sometimes used as 'tapes' to do file save. The other end of the pipe can be connected to a serial device, a communication server process... Therefore, when this signal is raised, the write system calls aborts.In an application environment, this signal should be caught and a message sent to the user saying 'Communication Server not Ready', for instance. The write system call would then be interrupted, reported to the save process as a 'parity' error, and the write would be retried until the write finally succeeds.

SIGALRM Alarm clock. The default signal handler is a simple return. Therefore, the signal is active, but does nothing. It can be used in FlashBASIC or Pick/BASIC, with the %alarm() function, do set time outs around critical sections. This signal can be altered by the TCL trap alrm command.

SIGTERM Software termination signal. This signals terminates the Pick process, leaving it logged on, but disconnected. This signal 'freezes' the Pick environment. If the process is restarted, execution will resume where it stopped. Normally, this signal should be preceded by a SIGHUP to log the process off.

SIGUSR1 User-defined signal 1. Not used. Can be used freely by the applications.

SIGUSR2 User-defined signal 2. Force the process to examine its current state, possibly changing it. This signal is used for Pick message, by the TCL logoff , TCL , END commands. Sending this signal out of context will cause no harm. This should be the way, for instance, to wake up a process waiting in a %pause() system call. This signal can be used by applications, provided they call the Pick signal handler inside their customized signal handler. See the section about the examples below.

SIGCLD Death of a child. Not used.

SIGPWR Power fail. When received, the process is logged off Pick, but remains connected to the virtual machine. The behavior of the system depends on how the hardware generates this signal. If there is no battery back-up, it is unlikely that the virtual machine will be brought down gently. The system usually change its running state, which will control what happens. A ap - k command should be inserted in the appropriate shell script associated to the new run level. This signal can be altered by the TCL trap pwr command.


Pick Signal System Call

The Pick monitor provides a system call to inform the Pick Virtual environment of an incoming signal. This C function is normally called by the default signal system handlers, but it can be called by an application signal handler too.

This function is defined as follows:

#include "/usr/lib/pick/include/sigmon.h"

void sigmon( code )
int code;

code is the action code, as described in the following table. Note some functions do not return to the caller .


Code Value/Description
db_slcout 0/No operation. Simply forces the process to examine its current state. This function must be called by the SIGUSR2 signal handler.

db_privop 7/Privileged opcode. Sends the caller to the system debugger. This call does not return to the caller. This call can be used to abort a C program, even if not called from a signal handler.

db_break 10/Interrupt. Sends the process to the FlashBASIC, Pick/BASIC, or system debugger. This function must be called by the SIGINT signal handler. Going to the system debugger is not immediate. Normally, the process will enter the debugger (or push a level) when the signal handler terminates.

db_esc 12/Quit. Pushes a level . This function must be called by the SIGQUIT signal handler. Normally, the process will push a level when the signal handler terminates.

db_logoff 14/Log off. This function is normally called by the SIGHUP handler. It can be called by other signal handlers as part of the application (like SIGALRM for instance, to log off a process after a given time).

db_pwrdown -1/Disconnect. The process is disconnected from the virtual machine, but remains logged on.


Examples

This sections shows some simple examples of using signals in a Pick application, or cooperating with Unix applications. All these examples require writing a C signal handler, which must be linked with the Pick monitor, as detailed in this document.

Time out

The purpose is to write a signal handler which will log the user process off if there is no activity for a given time. It is assumed the user is in a FlashBASIC or Pick/BASIC application, waiting input.

- Write the following signal handler and function

setalrm.c:

#include <signal.h>
#include "/usr/lib/pick/include/sigmon.h"

myalrm(){
/* signal handler. When activated,
log the process off */
sigmon( db_logoff );
}

/* Set the new signal handler
Set the signal handler to
the application signal handler.
Return the address of the
previous signal handler, so
that the basic application
can remove the time out
*/

void (*setalrm())(){
return signal(SIGALRM, myalrm );
}
<

- Compile the previous program and incorporate it to the Pick monitor, by typing, in the dm account:

addbi setalrm signal
ar vru libgm.a setalrm.o
make -f /usr/lib/pick/Makefile

Note this incorporates the user-defined function setalrm() as well as the system call signal() not normally shipped with the Monitor. The latter will be extracted from the standard C library. The %setalrm function can then be called from FlashBASIC or Pick/BASIC.

- Enter the following 'application' program

*
* Reprogram the alarm handler,
* keeping the previous system
* handler
* Note the function pointer
* returned by the function
* is treated as a pointer to a character.

include dm,bp,unix.h signal.h
old$alarm = (char*)%setalrm()
*
loop
* Set the alarm to 10 minutes
* From now on, if the user
* doesn't enter a command before
* 10 minutes, the process will
* be logged off.
%alarm(600)
* .. display application entry screen here
crt 'Command : ':
input command
while 1 do
begin case
case command = 'a'
* ... put command 'a' routine
case command = 'end'
print 'end of the application'
* disable the alarm and set the default alarm
* handler back to the default.
%alarm( 0 )
%signal( SIGALRM, (char*)old$alarm )
chain 'off'
end case
repeat

Note that, in the example above, if the alarm was not disabled and if the signal handler is not reset to the default, the alarm clock would have continued to run, even if the process went back to TCL, thus logging it off later. A small FlashBASIC or Pick/BASIC program, just rearming the alarm can be written to incorporate the alarm in PROCs or menus to achieve the same time out capability in TCL.

Synchronizing Two Pick Processes

On conventional Pick implementations, synchronizing two Pick processes is done either through polling for the existence of a file or, a little better, by using a FlashBASIC or Pick/BASIC LOCK instruction. On most implementations, however, the FlashBASIC or Pick/BASIC LOCK instruction itself involves, internally, a polling, thus making the waiting process to consume cpu resource. By using signals, it is possible to have a process waiting for a signal to occur (a BREAK, logoff or a signal generated by another process, possibly a Unix process or a Pick process from another Pick virtual machine) without any cpu consumption.

The following example has one phantom task waiting for a signal sent by 'somebody' to go read a message in a pipe where the 'somebody' has deposited a message. This communication with message, probably, would be better achieved through Unix messages, but this is merely an example. Also, this is a one to one communication. Multiple partners in this scheme would require semaphores. The server process makes itself visible to the entire system (Pick and Unix) by writing a temporary file which contains its process id, which other processes use to send a signal to it.

The (simple) signal handler uses SIGUSR1 . The 'message' is in ASCII, containing a header and some data. The message has the following format:

+---+---+--------//-----------+
| |NL | +
+---+---+--------//-----------+
| | |
| | +- Data (code dependant)
| +------------ New line (discarded)
+---------------- Command code.
T : Terminate
M : Message
R : file receive
- Enter the following C signal handler:


setusr1.c:

#include <signal.h>
#include "/usr/lib/pick/include/sigmon.h"

myusr1(){
/* Just reset the signal for next time */
signal( SIGUSR1, myusr1 );
}

/* Set the new signal handler
Set the signal handler to the
application signal handler.
Return the address of the
previous signal handler
so that the basic application
can remove the time out
*/

void (*setusr1())(){
return signal(SIGUSR1, myusr1 );
}

- Enter the following phantom task code in the item dm,bp, pserver :

pserver
001 !
002 * Example of a file server running as
003 * a phantom
004 * Commands are received on a named pipe.
005 *
006 include dm,bp,unix.h signal.h
007 include dm,bp,unix.h mode.h
008 include dm,bp,unix.h fcntl.h
009 *
010 * Defines:
011 equ NL to char(10) ;* UNIX line terminator
012 equ AM to char(254)
013 equ PIPE to "/dev/mypipe"
014 equ BUFSIZE to 10000 ;* max message size
015 *
016 char buffer[BUFSIZE]
107 *
018 * Remove temporary file
019 execute '!rm -f /tmp/pserverid'
020 *
021 restart:*
022 *
023 * Open the communication pipe in read
024 * only, no wait on read
025 * If open error, stop, sending a
026 * message back to the originating
027 * process.
028 fd=%open(PIPE, O$RDONLY+O$NDELAY)
029 if fd<0 then
030 stop 1,"Cannot open '":PIPE:"'. Error ":system(0)
031 end
032 *
033 * Do not allow BREAK from now on
034 break off
035 *
036 * Create the temporary file which
037 * contains our pid, so that
038 * everybody on the system will
039 * know the server id
040 mypid=%pgetpid(-1)
041 execute "!echo ":mypid:" > /tmp/pserverid"
042 *
043 * Reprogram the alarm handler,
044 * keeping the previous system handler
045 * Note the function pointer returned
046 * by the function is treated as
047 * a pointer to a character.
048 old$usr1 = (char*)%setusr1()
049 *
050 * Go try read the pipe. If there is no
051 * message, the signal we received
052 * was not an application one. May be
053 * somebody tried to log us off
054 * so close the pipe, restore the
055 * signal and wait a bit. If we come
056 * come back, was a false alarm. Restart.
057 loop while 1 do
058 * Wait for a signal
059 %pause()
060 *
061 * Read the pipe
062 n=%read(fd, buffer, BUFSIZE )
063 *
064 begin case
065 case n=-1
066 * IO error
067 gosub terminate
068 stop 1,"PSERVER: IO error ":system(0)
069 case n=0
070 * Pipe is empty...
071 * The signals we got is not
072 * the one we expected. Enable
073 * break to allow for a
074 * possible
075 * logoff, and restart
076 gosub terminate
077 sleep 1
078 goto restart
079 case 1
080 * Got something (n is the
081 * number of byte)
082 * The 1st byte is a code,
083 * the second a new line
084 * (discarded)
085 code=buffer[1,1]
086 message=buffer[3,n-2]
087 * Go handle the message
088 gosub do$it
089 end case
090 repeat
091 *
092 do$it:*
093 begin case
094 case code='T'
095 * Terminate
096 gosub terminate
097 stop 1,"PSERVER: Terminated"
098 case code='M'
099 * Message.
100 execute "msg * PSERVER: ":message
101 case code='R'
102 * Receive a file. The message is
103 * full filename (NL) item (NL)
104 * text
105 convert NL to AM in message
106 filename=message<1>
107 item=message<2>
108 message=delete(message,1)
109 message=delete(message,1)
110 open filename then
111 write message on item
112 close
113 end else
114 execute "msg !0 PSERVER: '":filename:"' is not filename"
115 end
116 end case
117 *
118 return
119 *
120 * Clean everything
121 terminate:*
122 %close(fd)
123 %signal( SIGUSR1, (char*)old$usr1 )
124 execute '!rm -f /tmp/pserverid'
125 break on
126 return
127 *
128 end


- Create a communication pipe by doing the following from TCL:

su (must be superuser to do the following )
mknod /dev/mypipe p
chmod 0666 /dev/mypipe
exit (Get back to TCL)

- Compile and catalog the FlashBASIC or Pick/BASIC program, compile the C program and add it to the built in function list by:


addbi setusr1
cc -c setusr1.c
ar vru libgmu.a setusr1.o

To be able to use the customized monitor with a phantom process, it is necessary to shutdown and to move the customized monitor to the common directory /usr/bin while being in single user mode.

shutdown
make -f /usr/lib/pick/Makefile
init s (wait for the system to effectively go to single user)
mv /usr/bin/ap /usr/bin/ap.save
mv ./ap /usr/bin
init 2 (go back to multiuser)

Restart the Pick virtual machine.

- Create the phantom task server:

z pserver

- The server is now waiting for a signal to read the message. Normally, this would be done by another process (Pick or Unix), but, just to test this, the following shell script allows sending messages, small Unix files or terminate the server:

snd:

# Send a command to pserver through a pipe
PIPE=/dev/mypipe # the communication pipe
SERVERID=/tmp/pserverid # where the server puts its PID
COMMAND=$1

# Make sure the Pick server is active
if [ ! -r $SERVERID ]
then
echo Pick server is not active
exit 1
fi
# Get the server pid
PSERVERID=`cat $SERVERID`

# Send it a signal 0 to test its existence
kill -0 $PSERVERID
if [ $? != 0 ]
then
echo Pick server is not active. PID is not valid.
exit 1
fi

# Parse command
case $COMMAND in
"r"|"R")
# Receive a file : snd r unix.file
# pick.file item
echo "Rn$3n$4n~`cat $2~`" > $PIPE
;;
"m"|"M")
# Send a message: snd m <text>
shift
echo "Mn$*" > $PIPE
;;
"t"|"T")
# Terminate
echo "Tn" > $PIPE
;;
*)
echo "usage: snd r unix.file pick.file item"
echo " snd m message"
echo " snd t"
;;
esac

# Wake up the server by sending SIGUSR1
# -30 for AIX; -16 for SCO, DG
kill -30 $PSERVERID

- Test the server by the following commands (from Shell):

snd m Hi there

This command should send a Pick message to all Pick users.

snd r /etc/inittab dm,pointer-file, inittab

This command should send the Unix file /etc/inittab into the Pick item dm,pointer-file, inittab .

snd t

This command should terminate the server process.
Syntax
Options
Example
Purpose
Related

tcl.update-md

Command tcl.update-md Verb: Access/TCL
Applicable release versions: AP, R83
Category TCL (746)
Description updates the verbs and related items in a given account md, using the "newac" file on the "dm" account as the base standard for determining what should be there. It must be run from the "dm" account.

"update-md" checks for illegal verb definitions and converts "old" catalog pointer items to AP format.

An "active list" (consisting of account names) may be used prior to running "update-md" to update several accounts at once.

If no account name is specified, and no list is active, the system requests the account name.

The process prompts with the following messages:

Create user id from each account name (y, <n>)?

This prompt allows the automatic creation of user-ids corresponding to any account updated. Valid responses are "y", "n", or "<return>", which defaults to "n".

Enter md file name:

This is where the "new" account name is entered. Entering a <return> at this prompt terminates the process.

"update-account" and "update-accounts" are synonyms of "update-md".
Syntax update-md {account.name}
Options
Example
update-md
Create user id from each account name (y, <n>)?n
Enter md file name:production
Purpose
Related account.adi
filename.clashes
tcl.update-accounts
tcl.update-account
filename.md
filename.newac
tcl.account-restore

basic.$options

Command basic.$options Statement/BASIC Program
Applicable release versions: AP 6.2
Category BASIC Program (486)
Description sets compatibility options for the BASIC compiler.

By default, the compiler generates code compatible with the classic Advanced Pick product. The "$options" statement allows the use of new statements and functions as well as closer functional compatibility with other flavors of Pick. The following "tag"'s are currently available:


AP Advanced Pick - This is the default setting and provides code compatible with previous releases (provided new features are not used).

DEFAULT Default - This is the same as EXT and should be used as the new development default setting.

EXT Extended - This tag provides as many statements and functions as are available and should be used for all new development. Note that because many new functions are allowed, that array references in existing code may need to be changed to some other name for proper compilation.

GA General Automation - This is similar to the EXT option, but provides tighter GA compatibility with regards to the locate and match statements. It is suggested not to use this mode for new development as this setting will disallow any functions not provided by General Automation Pick.

IN2 IN2 - Currently the same as "EXT". Further compatibility changes may be made in the future to bring this setting closer to IN2 compatibility. Never use this setting for new development.

INFORMATION Prime Information - Currently the same as "EXT". Further compatibility changes may be made in the future to bring this setting closer to Prime Information compatibility. Never use this setting for new development.

PICK Pick System's R83 - Same as R83.

R83 Pick System's R83 - Currently the same as AP. Future development may make minor changes to allow slightly better run-time R83 compatibility. Never use this option for new development.

REALITY Reality - Currently the same as "EXT". Further compatibility changes may be made in the future to bring this setting closer to Reality compatibility. Never use this setting for new development.

It is suggested to use the "$options" statement at the top of the desired modules. Note that the default setting is "AP", but this can be changed by setting the shell variable "@SYS.COMPILER" to one of the above tags.

It is illegal to use the "$options" statement multiple times within the same source item.
Syntax $options {tag}
Options
Example
$options ext
x="abc"
print ereplace(x,"a","b")

"bbc"
Purpose
Related basic.swap
basic.scan
basic.convertfn
basic.summation
basic.dquote
basic.squote
basic.exchange
basic.fmt
basic.inmat
basic.maximum
basic.minimum
basic.spooler
basic.status
basic.trimf
basic.trimb
basic.ifr
basic.compare
tcl.@

access.phrases

Command access.phrases Definition/Access: Verbs
Applicable release versions: AP 6.1
Category Access: Verbs (152)
Description Phrases must be defined in the dictionary of the file for which the phrase will be used (or in the account's master dictionary). Line one of the phrase definition must be an H. Line two of the phrase definition contains the words which make up the phrase.

Phrases may contain any legal Access words and constructions except verbs and file names. This includes output attributes, headings, footings, selection criteria, modifiers (ID-SUPP, DBL-SPC, etc.), even explicit item-id's. Phrases may contain other phrases. Circular phrase references are not permitted and result in an error message.

It is possible to store a collection of phrases in a file and reference them by means of a "remote" phrase definition. A remote phrase definition contains an R on line 1, the phrase file name on line 2, and the phrase item-id on line 3. The item in the remote phrase file must be a phrase definition (H on line 1), and the file and item must exist.

A special phrase may exist in the file dictionary (or in the account's master dictionary if the DICT modifier is specified) which defines the default output attribute list when no explicit attribute names have been included for output. The item-id of this special phrase is the at-sign followed by the file name (_@filename) or, optionally, just the at-sign (_@). This phrase defines the default output attribute list in the case no output attributes are specified in the sentence. This is used in place of the conventional numbered output attributes (1,2,3...). If the _@filename phrase is missing, then the _@ phrase is assumed to define the default output attributes. Using this method, dictionaries which define several data files may use different output attribute list phrases.

The _@ phrase may have an H or R on line 1, in which case numbered attribute names are illegal. If line 1 is an H or R, all un-quoted words which consist of numeric digits are treated as values. That is, if a user's master dictionary contained the _@ phrase with an H or R on line 1, the statement "LIST MD 1 2 3" would list only items '1' '2' and '3' using the default output attribute list (from the _@ phrase).

Alternatively, if line 1 of the _@ phrase contained an HZ or RZ, numbered attribute names are allowed and will only be considered as values if they do not exist as attribute definitions. For example, if a user's master dictionary contained the _@ phrase with an HZ or RZ on line 1, the statement "LIST MD 1 2 3" would list the entire master dictionary displaying attributes 1, 2, and 3 (provided that 1, 2, and 3 were attribute definitions in the master dictionary).
Syntax
Options
Example
By definition a phrase may be any syntactically complete portion of an Access 
statment except verbs and file names.  For example, a phrase named ADDRESS.LIST 
in the file CLIENT could be used to display NAME and ADDRESS:

ADDRESS.LIST
001 H
002 NAME STREET CITY STATE ZIP

Once defined in the DICT of the file CLIENT this phrase may be used in an 
Access query such as:

SORT CLIENT WITH STATUS = ACTIVE BY ZIP ADDRESS.LIST LPTR

This statement would produce a report of clients defined as ACTIVE in the data 
file and using the phrase definition ADDRESS.LIST as the output specifications. 
 Please note that the selection value ACTIVE is not enclosed in quote marks; 
another feature of the Access pre-processor.

A HEADING statement could have been included in the phrase ADDRESS.LIST, 
however, a more effective method may be the use of a "remote phrase." 
 For example a remote phrase file called STAFF could be created containing 
HEADING phrases for each staff member. To use remote phrases an 'R' 
type phrase is required in the DICT of the file CLIENT, as well as, a phrase in 
the data file STAFF.

DICT of CLIENT
JIM
001 R
002 STAFF
003 JIM.JONES

DATA of STAFF
JIM.JONES
001 H
002 HEADING "Page 'P'   PREPARED FOR JIM JONES   
'CTLL'"

Now the Access statement:

SORT CLIENT WITH STATUS = ACTIVE BY ZIP JIM ADDRESS.LIST LPTR

Would produce the same report as in the previous example, however, the 
'R' type phrase 'JIM' in the DICT of CLIENT will capture 
the HEADING from the STAFF file. Multiple remote phrase files may be used (i.e. 
FROM could be a file of desired FOOTINGs).
 NOTE  !!!  :  If a code of 'A' was stored in the data file of CLIENT 
as the method of indicating a client as ACTIVE the above example would require 
the statement be entered as:

SORT CLIENT WITH STATUS = "A" BY ZIP JIM ADDRESS.LIST LPTR

This is due to the fact that "A" is defined in the MASTER DICTIONARY 
as a throw away CONNECTIVE and the quote marks are needed to resolve any 
ambiguity.  This would also apply to other words which are defined in the MD.
 Another type of phrase which may be used is the _@filename phrase. The 
_@filename phrase is used to define the default output  attributes when no 
output specifications are included in the Access statement.  For example, the 
_@filename phrase for the file CLIENT would be created in the DICT of CLIENT 
under the name _@CLIENT:

_@CLIENT
001 H
002 NAME CITY PHONE CONTACT

Now if the LIST or SORT verbs are used to query the file CLIENT the attributes 
NAME, CITY, PHONE and CONTACT will be the output for statements such as:

LIST CLIENT HEADING "Page 'P'    CLIENT DEFAULT LIST 
'CTL'"

or

SORT CLIENT BY NAME WITH TYPE = VAR

The above statements contain no output specifications, therefore, the _@CLIENT 
phrase is used to determine the output.

If the statement was entered as:

SORT CLIENT BY NAME NAME STREET CITY STATE ZIP

Then the default output attributes defined in _@CLIENT would be ignored and the 
output list requested would be used.

NOTE  !!!  :  If line 001 is defined as HZ or RZ (remote) then attribute 
numbers (i.e. 1 2 5 7 8) may be used on line 002 to extract the data in those 
attribute AMC id's, provided that those AMC numbers are defined in the 
file dictionary.
 The _@filename phrase may also be just the _@ sign and the filename will be 
assumed.  Also if Q-pointer(s) exist for the file the _@filename for the actual 
file will be used to determine the output attributes. For example, if CUST is a 
Q-pointer to the file CLIENT and the Access statement is entered:

LIST CUST

Then the _@CLIENT default attribute phrase would be used. In other words, 
_@CUST is not required and is not valid!
 A special use of the _@filename phrase occurs in the case when multiple data 
sections are defined in a dictionary. For example, if in the DICT of our CLIENT 
file a data section for ACTIVE and another for INACTIVE are defined then a 
separate _@filename phrase may also be defined for each data section.

 DICT of CLIENT       DICT of CLIENT
 _@ACTIVE             _@INACTIVE
 001 H                001 H
 002 NAME CITY PHONE  002 NAME CITY STATE ZIP

Now if the CLIENT file was querried: 

LIST CLIENT,ACTIVE

the pre-processor would use the _@ACTIVE filename phrase to determine the 
default output attributes.  And if the file was querried:

LIST CLIENT,INACTIVE

the pre-processor would use the _@INACTIVE filename phrase to determine the 
default output attributes.
Purpose
Related access.pre-processor

up.prestore

Command up.prestore Command/Update Processor
Applicable release versions: AP
Category Update Processor (113)
Description defines a series of Update processor commands 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.

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 cursor movement commands.

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 as items in a file. The items remain in the file until they are deleted or overwritten.

"md" is the default file used for saving prestore commands, but any legal file.reference may be used.

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 a UP command is included as part of the prestore command, the UP command is typed in WITHOUT depressing the control key. The Update processor interprets anything in the command that is NOT in quote marks as a UP command.
Syntax
Options
Example
Purpose
Related up.zl
up.p
up.z
up.zw
up.zn
up.zr
up.cursor.movement
up

ue.$uex.rel.buf

Command ue.$uex.rel.buf User Exit/BASIC Program
Applicable release versions:
Category BASIC Program (486)
Description The "u$uex.rel.buf" user exit released a block of consecutive frames in memory previously allocated by "u$uex.get.buf".

"block.info" is a dynamic array which contains the following information:
block.info<1> = base address of frames to be released (address is composed of segment:offset)
block.info<2> = number of frames to be released

"result" is a status code indicating:
'0' = successful
'1' = illegal base address segment:offset
'2' = result<2>: number of frames not released
Syntax result = oconv(block.info,"u$uex.rel.buf")
Options
Example
code = 
oconv("6000:0"<am>"128","u$uex.rel.buf")
Purpose
Related ue.$uex.get.buf

pa

Command pa Definition/General
Applicable release versions: AP
Category General (155)
Description Demonstration account.

used to:

Enter and organize names, addresses, and phone numbers.
Write checks and balance the account to a bank statement.
Prepare and print expense reports.

PA consists of one menu, two macros, two primary files, four secondary files, and eight Pick/BASIC programs. Most PA data processing functions are accomplished using standard system processing codes stored in the dictionaries of the files.

Data entry screens are generated using the Update processor (UP). The reports associated with the PA application are generated using standard Access statements.

PA uses two primary files: entity and journal. The entity file stores information about people and companies. A subset of the entity file is payees. The journal file stores information about checks written and deposits made.

Secondary files to entity are the zip code file (zcf) and the country file (country) which are used to translate the postal codes stored in the entity file into a city-state-zip combination (e.g., 92714, translates to Irvine CA 92714).

Secondary files associated with the journal file are location and category. These files compare input values to predefined values in the associated attributes in the journal file. These files are also used to validate cost groupings and categories to which expenses can be allocated for a journal item (check).


Using PA

Advanced Pick comes with a standard PA account. To logon to the pa account, type

to pa

The PA menu will be displayed.

The PA account has data in the entity, journal, zcf, and country files. The entity file contains data about Pick licensees, dealers, application developer's user groups, etc. The zcf file contains a sampling of international postal codes and post office locations.

Help can be accessed by pressing ? followed by the option number and m from the menu or by pressing ? on an attribute in a data entry screen. Help information displays on the bottom portion of the display. The expense report options (11 and 12) execute macros which display TCL statements. Changes may be made to the statements. To change the date, just type the new date over the existing date. To send the output to the printer, type (p at the end of the statement. To execute the statement, press m.


entity file

The functions of the entiry file is similar to a telephone book. Each item in the entity file represents an entry in the book. The difference between Pick and the telephone book, is that the number of entries (items) in Pick is virtually limitless. Plus, each item is instantly accessible by cruising on one of the many defined indexes. The entity file contains an item for each person or company. Attributes for items in the entity file may contain name, address, postal location, and phone number. A comments attribute is available to enter any additional data about a person or company. Another advantage Pick has over a telephone book is that the data is not limited to one telephone number or one line of comments per entry. The amount of data that may be entered about a person or company is unlimited.

An entity-type file is at the heart of almost every computerized business application. Every other application should refer to that entity file. Name and address information should not be embedded in other applications.


entity Dictionary

The entity file is controlled through the entity dictionary. A summary of the entity dicitonary is listed below. (For a complete listing of the entity dictionary use the ld command.

1 name Name of person or company. Only one value may be entered for this attibute.
2 address Street address. Maximum of two lines allowed.
3 zip Contains a postal code (in the US aka zip code) which is used as an item-id in the zcf file allowing conversion to the associated city, state and country.
4 phone Enter the phone number as a series of numeric digits as you would dial. You may follow the numeric portion of the phone number with any amount of additional data. The subroutine 'phone' transforms the numeric phone into a domestic or foreign format depending on the contents of the zip code attribute and appends it with any data you input following the numerics.
5 codes Translated value of the code; at a minimum: c for company or p for person. Other codes may be added.
6 sic Standard industry classification code for associated company.
7 surname Contains the last name of the person for browsing and sort purposes.
8 title Persons title. Normally job related.
9 category Used when a check is a regular recurring expense. This value will automatically be entered into the category attribute in a new check.
10 employees Displays the employee names for this 'company' entity item.
11 birthdate Birthdate of person.
12 comments Contains any test you want.
13 fax Displays the fax number for this entity item.


Zip Code File (zcf)

The Zip Code file (zcf) is correlated with the zip attribute in the entity file. The zcf file has the postal codes as item-ids and associated location information--city and state--as attribute values. For United States zip codes, the item-id is a five-digit number. An alpha suffix is appended to the five-digit number to indicate a different city with the same zip code.

There is also a country file which contains the international country code as the item-id. The country name is stored in the first attribute. If a country has a postal code system, that country's code has the country code as a prefix followed by a period.

The zcf file supplied with the PA account contains a subset of Pick's fifty-thousand plus international zip code file. The complete file is available from Pick Systems. Updates to this file are also available.


zcf Dictionary

1 city Name of city associated with postal code.
2 state Name of state or in the case of foreign codes the province associated with the postal code.


Journal File

The PA journal file is similar to a standard accounting journal except the PA journal deals only with expenses. The journal file contains an item for every check. A journal item is made up of the date of the transaction, the amount of the transaction, the person/company to whom the transaction was made, and the reason for the transaction (location and category).

To reduce data entry when creating checks, the entity file has attributes (location, category, amount, and ref) for regularly occurring payments such as mortgage, car, utilities, etc. When a payee is entered using the Update processor in a new journal item, these attribute values from the payee item in the entity file are plugged into the journal item.

Sorting the journal detail creates expense general ledger reports. The PA menu provides monthly and quarterly ledger reports. These reports are created using Access statements and can be easily modified.


Journal Dictionary

0 tly Attribute always returns a value of 'one'. Used to total occurances with a det-supp connective.
1 cd legal journal code types are: c check, d deposit, s statement beginning balance. a p code is temporary and causes a check to be printed when the journal item is filed.
2 date Effective date of journal transaction. normally the date the check was written or the deposit made.
3 payee single valued attribute contains item-id of the payee in the entity file. you can zoom and double clutch cruise on this attribute
4 category category is the type of expense that the check represents, such as utilities or mortgage. a journal item may have multiple categories each associated with a corresponding location and amount. the index on this attribute permits browsing through items in the journal file by category.
5 location Major cost grouping. Each one has an associated category and amount. Multiple associated sets of location, category and amount are used to allocate costs for a single check to a payee. An index on this attribute permits browsing through items in the journal file by location.
6 amount amount, to the penny, allocated to the correlated category and location; entered without decimal points or commas.
7 comments any comments you may wish to make about the journal item. you may enter as much data as you want.
8 ref A payee's account or reference number. For the payees convenience this data prints on the check.
9 chk# number of the check written. will be plugged with a next check number for new checks. check to see match with actual check in printer and change if wrong. this number will be automatically incremented as you write checks.
10 bank.date the date of the bank statement associated with the check, deposit or beginning balance.


Writing Checks

PA was developed to print checks one after another until all of the bills have been paid. When writing the checks, press <return> to display a new item (check) after each filing. To print a check, file a journal item using a code of 'p'. The check is sent immediately to the printer.

The check layout was chosen, in par, to accommodate a standard stock #10 window envelope to show the payee and the return address. If a different check layout is to be used, journal.upd can be changed. A copy of the check is not needed since there is a record of the payment in the computer and the check is generally sent back with the bank statement.

Prior to printing the checks, insert and align the check stock in the printer. As a double check, the check number known by the computer is printed on the check adjacent to the preprinted check number. To initialize the check number so it matches your checks, update dict journal ck.num. Attribute 1 contains the check number.


Entering Deposits

The PA accounting function is primarily cost reporting. Deposits are itemized in the journal sot that the account can be balanced to a bank statement. Since deposits do not enter into expense reports, amounts are stored as negative numbers so that the expenses may be shown as positive numbers.

When filing a new journal item with a d (deposit) code, the Pick/BASIC program journal.upd does the following:

Sets payee and chk# to null
Sets location to bank
Sets category to deposit
Checks for a numeric amount and forces a negative amount


Balancing to a Bank Statement

Balancing involves entering the date of the bank statement in each journal transaction. The balance program is initally used to enter check ranges and deposit dates. Subsequent entries required to balance the account are done using UP on the journal file followed by the balancing only portion of the balance program.

The balance program first prompts for a statement date followed by the beginning balance. An item with a beginning balance code is created in the journal file to store the beginning balance. Beginning balances must be entered with reversed signs, i.e., a negative number must be entered for a positive beginning balance. Once a beginning balance has been entered for a particular date, the beginning balance prompt may be skipped.

Each check number cleared by the bank is entered. This is done by entering individual check numbers or ranges of check numbers separated by a period. After all checks have been input enter a null value to terminate the check number prompting.

Deposits are cleared by entering the deposit dates shown on the statement. After terminating deposit date entry with a null value, the balance program prints the beginning balance, total credits (deposits), total debits (checks), and the ending balance. A negative ending balance is actually a positive cash position at the bank. If the ending balance does not match the balance shown on the statement, detail information can be displayed.

After the journal is updated and/or corrected so that it balances, it can still be viewed and changed at a future time. After the prompt for statement date, all othe prompt may be skipped. The result should always match a previously balanced statement.


The Update Processor

All data entry is performed under the control of the Update processor (UP). From any attribute in the UP a ? may be pressed to bring up the help text for the attribute. To cruise through the chk#, date, payee, location, category, and amount, use control-f to go forward and use control-d to go backward.

The payee attribute in the journal file allows zooming, as well as double-clutch cruising. Typing control-g at the end of the value zooms into the correlated item in the entity file. When in the entity file, updates may be entered, as required. Control-u and control-y browse on potential payees in th entity file.


Saving and Restoring

Option 15, of the PA menu options runs account-save which prompts for the account name to be saved to floppy disk. This account-save disk may be used at a future time to restore the entire account or a portion of it.
Syntax
Options
Example
Purpose
Related tcl.pa

update.processor

Command update.processor Definition/Update Processor
Applicable release versions: AP
Category Update Processor (113)
Description a dictionary-driven, full-screen editor and data processor.

UP can be used to view, create and manipulate items in files. 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 in conjunction with the Output processor (OP), UP operates as a document processor.

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.

B-tree indexes permit cruising from item to item on an attribute value sequence and from value to value in a remote file. See "index, remote" and "index, local".

Pick/BASIC subroutines can be called from attribute-defining items and file-defining items allowing absolute control of all data entry using the Update processor and dictionaries.

When evoked, UP copies the specified item to a workspace and displays as much of the item on the screen as it can. (In most applications, each input "screen" fits within a real screen.)

Any unprintable characters embedded within the item are displayed as a dot "." on AP 6.1.0 and up.

Control keys are used to perform editing functions, but as long as the control key is not pressed, all characters are entered as typed.

An optional spelling checker beeps and rejects input if a character is typed that does not lead to a legal word. See "spelling checker".

UP commands begin with a control character formed by simultaneously pressing the "<ctrl>" ("control") key and one or more alpha keys. Some UP commands require more command characters, while others require text input. The second UP command can be entered as straight alpha or with "<ctrl>" depressed. On some terminals a "<ctrl>+s" leaves the terminal locked. To unlock the terminal, type "<ctrl>+q". See "commands, up".

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 is not changed.

Without any attribute-defining items specified, UP functions as a full-screen editor.

Value marks are indicated by line breaks with no attribute label.
Syntax
Options i Include item-id in UP workspace.

l Look only. The item cannot be filed or deleted.

r Raw option. Display non-printable characters as periods. The escape character is displayed as a "[". The sub-value mark is displayed as a "" character.

s Toggle off the spelling checker.
Example
Purpose
Related tcl.update
attribute-name
tcl.spelling.checker
conversion
dictionaries.as.operators
up.a
up.sc.aa
up.sc.aaa
up.b
up.c
up.cc
up.cd
up.cl
up.cp
up.cr
up.cw
up.d
up.e
up.f
up.g
up.h
up.i
up.j
up.k
up.l
up.m
up.n
up.o
up.v
up.w
up.x
up.x0
up.x1
up.x2
up.x3
up.x4
up.x5
up.x6
up.x7
up.x8
up.x9
up.xb
up.xc
up.xe
up.xf
up.xi
up.xk
up.xl
up.xn
up.xo
up.xp
up.xr
up.xs
up.xx
up.y
up.z
up.za
up.zb
up.zc
up.zd
up.ze
up.zg
up.zh
up.zl
up.zn
up.zo
up.zp
up.zq
up.zr
up.zs
up.zt
up.zw
up.zz
up.znumber
up.overtype.mode
up.only
up.search.replace
zooming
tcl.config
up.data-entry
access.id-prompt
up.input-conversion.fdi
double.clutching
up.exit.item
basic.debugger.edit
up.delete.text
up.cursor.movement
tcl.ed
pc.value.limit
up
up.zx

basic.cfunc

Command basic.cfunc Definition/BASIC Program
Applicable release versions: AP/Unix, AP/DOS
Category BASIC Program (486)
Description can be called from a Pick/BASIC program or subroutine in AP/DOS and AP/Unix implementations using a syntax similar to that of normal C.

Commonly used functions are included in the run time package and require no special linking. These functions are referred to as built-in functions. A 'user-defined' function may also be included in a Pick/BASIC application by linking it with the Monitor, thus making a 'user-defined built-in' function.

C function calls can be embedded in Pick/BASIC expressions, Pick/BASIC statements or can be used as arguments to other C function calls. Combined size of all parameters passed may NOT exceed 32 KB. This size can be changed, however, by the "set-cmem" TCL command.

If a "type" specifier is omitted before an argument name, the argument is assumed to be of type integer when "arg" is a number, or to be of type pointer when "arg" is a dynamic array (string). If type is omitted before the function name, the function is assumed to be of type integer.

"arg0" ... "argn" are the optional arguments to the function; up to 15 arguments are supported.

The return type of a function is "void" if the function is not part of an assignment statement or used as an argument to another C function or Pick/BASIC statement. Whenever the return value of a function can be neglected, the type can be overridden by (void).

When a call to a function is made:

- All arithmetic arguments are passed by value.

- All dimensioned arrays are passed by reference.

- All dynamic arrays (strings) are passed by reference.

- String constants (strings between quotes) and sub-strings (string[m,n]) cannot be modified. If a C function tries to modify a string beyond the end of the string, the string will be truncated to its original size but no error will be reported. As is usual in C, no data translation will occur implicitly.

- Pointers are all treated as pointers to characters. When assigned to a Pick/BASIC variable, a pointer can only be passed to another C function or be tested for the value 0 (NULL pointer), anything other than this makes no sense. The following statement has unpredictable results:

ptr=(char*)%malloc(1024)
if ptr > 0 then print 'ok'

The only valid form is to test for ptr = 0 or ptr # 0.

Argument Types

The following argument types are supported:

<nothing>

Default. If "arg" is a number, an (int) is passed to the function. If "arg" is a dynamic array (string), a pointer to the first character of the string is passed to the function. If "arg" is a dimensioned array, a pointer to an image of the dimensioned array is passed to the function. See 'Passing Dimensioned Arrays' below.

(int) (AP/Unix)

Integer. The "arg" is divided by the PRECISION factor and passed to the C function. Integers are 32 bit signed elements.

(int) (AP/DOS)

Integer. The "arg" is divided by the PRECISION factor and passed to the C function. Integers are signed and can be in the range -32767 to 32767. Integers larger than 16 bits ( '+' or '-' 32767) are currently not supported and if they are used, they will cause unpredictable results.

(char)

Character. If "arg" is a dynamic array (string), the first character is passed to the C function. If "arg" is a number it is divided by the PRECISION factor and the result is truncated to 8 bits and passed to the C function.

(char*)

Pointer. The "arg" is a number which is passed to the C function without being divided by the PRECISION factor. The only legal use of this type is to pass a null pointer or a pointer returned by a previous call to a C function to another C function.
All types, except pointers can be prefixed by the keyword "unsigned", (unsigned char) for example.

NOTE: The PRECISION factor is a number between 0 and 9, with 4 being the default value. When a number is divided by the PRECISION factor, the number is actually being divided by 10 raised to the power of PRECISION.

Passing Dimensioned Arrays

Dimensioned arrays of integers can be passed to an external C function. When the array is passed, the C function receives a pointer to the array and all the integers in the array are divided by the PRECISION factor. If the array is multidimensional, the integers are organized column by column. For example, if we have an array that is dimensioned to (2, 5) in Pick/BASIC, the values in the C "array" would be in this order: (1, 1), (2, 1), (1, 2), (2, 2), (1, 3), (2, 3), etc.

Function Types

The following function types are supported:

<nothing>

Default. The return value is assumed to be an integer. It is multiplied by the PRECISION factor.

(void)

The return value is discarded. When prefixed with this type, the function cannot be part of an assignment or be used as an argument to another C function or Pick/BASIC statement or function.

(int) (AP/Unix)

Integer. The return value is a signed integer. It is multiplied by the PRECISION factor.

(int) (AP/DOS)

Integer. The return value is a signed integer. It is multiplied by the PRECISION factor. Integers larger than 16 bit are currently not supported and if they are used, they will cause unpredictable results.

(char)

Character. The return value is stored as a dynamic array containing only one character.

(char*)

Pointer. The return value is stored without being multiplied by the PRECISION factor. The only legal use of this type is to store a pointer that will be used as an argument to another C function.

'Address of' Unary Operator

The C unary operator, & (ampersand), is used to pass the address of an integer to an external C function. This is the only valid form. Note that Pick/BASIC converts numbers which are too large into strings. In this case, the C function would receive a pointer to a character instead of a pointer to an integer.

Space Reserve Statement

When a Pick/BASIC variable (a dynamic array or an element of a one or two-dimensional array) is used to store data returned by a call to a C function (by means of a pointer passed as an argument), the Pick/BASIC variable must have been assigned a size before the call to the function. This needs to be done because C has no notion of dynamic arrays. If a size is not assigned before the result of a C function call is stored in the variable, the data is truncated. Space can be reserved using the following statement:

char variable[size] {,variable[size], ...}

This reserves at least "size" bytes for "variable". "size" can be a constant or an expression. "variable" can be a dynamic array or an element of a one or two-dimensional array. After reserving space for "variable", the content of the variable is undefined.

If a string longer than "size" is assigned to a variable, it is truncated and the characters beyond the given size are ignored. If a string shorter than "size" is assigned to variable, its content after the defined size remains undefined.

Static Data

When using 'user-defined built-in' functions, static data defined as part of a user-defined function remains valid as long as the Pick process is not disconnected from the virtual machine. This is true even if the Pick/BASIC program is finished executing and has returned to TCL. The scope of static data lasts longer than in conventional Unix or DOS programs.

Since static data takes up space in the data section of each Pick process (therefore main memory), it is not advisable to have large amounts of static space. This is especially true for AP/DOS which does not benefit from the underlying Unix virtual memory.

AP/Unix Includes

The following 'header files' are provided in the file bp,unix.h, in the dm account.

errno.h 'errno' values.
fcntl.h Codes for %open(), %creat
ipc.h Semaphores, shared memory, messages.
mode.h File access codes.
sem.h Semaphore operations.
signal.h Unix signal signal numbers.

AP/DOS Includes

The following 'header files' are provided in the file bp,dos, in the dm account.

errno.h MS-DOS/Unix 'errno' codes.
fcntl.h MS-DOS/Unix file access flags.
file.h File system constants.
screen.h Screen constants.
stddefs.h Standard constants.
usrexits.h User exits.

Use "see.also" for information on all system-defined built-in C functions. In most cases, no description is given unless there is something special to mention. Please refer to the Unix or the appropriate system documentation if more details are necessary.

The following rules apply when making a call to a C function:

- The parameters for each funtion must be enclosed in parentheses.
- There must be no spaces between the percent sign (%), the function name and the left parenthesis.
- The function is assumed to return an integer unless explicit casting is performed.
Syntax {variable=}{(type)}%function( {{(type)} arg0 {, ... {(type)} argn}} )
Options
Example
Purpose
Related basic.statements
basic.cfunc.user
tcl.set-cmem
basic.%chdir
basic.%chmod
basic.%chown
basic.%close
basic.%close.apdos
basic.%creat
basic.%dup
basic.%fclose
basic.%fdopen
basic.%fgetc
basic.%fgets
basic.%fprintf
basic.%fsize
basic.%getenv
basic.%getpgrp
basic.%getppid
basic.%ioctl
basic.%kill
basic.%memccpy
basic.%memcpy
basic.%pause
basic.%read
basic.%read.apdos
basic.%semctl
basic.%shmat
basic.%shmdt
basic.%shmget
basic.%write
basic.%write.apdos
basic.%alarm
basic.execute.unix
basic.%pgetpid
basic.cfunction
tcl.rmbi
basic.%lseek.apdos
basic.execute.apdos
basic.%whex
basic.%rdhex
basic.%memxcpy
basic.%free
basic.%popen
basic.%open.apdos
basic.%fputc
basic.%wait
basic.%freopen
basic.%fopen
basic.%pclose
basic.%fputs
basic.%getpid
basic.%lseek
tcl.addbi.apdos
tcl.listbi
basic.%ttyname
basic.%unlink
basic.%open
flash.basic.differences
basic.%
tcl.addbi.unix

access.total

Command access.total Modifier/Access: Verbs
Applicable release versions: AP, R83
Category Access: Verbs (152)
Description accumulates a columnar total for a specified attribute-defining item.

The optional "total-limiter" functions like the "value string" portion of the selection criteria process, limiting totals to values that pass the specified selection criteria.

"attr.name" is the name of the attribute whose values are to be totaled.

"operator" is any legal relational operator, such as "=". If no operator is specified, "=" (equal) is assumed.

"value.list" is a list of values to match, enclosed in (") (double quotes) or "" (backslashes).

If the "total" modifier is used in the same sentence as a "roll-on", subtotal values are generated whenever a break occurs.

The subtotal is displayed in the appropriate column for each attribute specified in a "total" modifier. At the end of the listing, a total is generated for each column.

In computing the value for accumulation, correlatives (attribute 8) are processed, but conversions (attribute 7) are applied to the totaled value.
Syntax total attr.name {"total-limiter"}
total attr.name {{operator} "value.list"
Options
Example
list invoices total amount total amount (p
list invoices total status "overdue"
list invoices total amount le "300" total amount gt "1000"
Purpose
Related access.roll-on
access.modifiers
access.break-on
access.det-supp
access.attr.name
access.grand-total
pc.xr

tcl.spelling.checker

Command tcl.spelling.checker Definition/Update Processor
Applicable release versions: AP
Category Update Processor (113)
Description provides an optional spelling checker facility to verify the spelling of text as it is entered.

During text entry using the Update processor, the spelling checker looks at each character to see if those typed so far make a legal word or may become a legal word. In releases of AP prior to 6.1.0, when an "illegal" word is encountered, the spelling checker beeps, stops entry and positions the cursor back one position, over the "illegal" character. At this point, a number of options are available:

1) The correct letter can be typed, assuming it was wrong.
2) "<ctrl>+a" accepts the word as shown.
3) "<ctrl>+a<ctrl>+a" accepts word and adds it to the "words" file,=.
4) "<ctrl>+a<ctrl>+a<ctrl>+a" disables the spelling checker.
5) "<ctrl>+f" views the next "legal" word in the "words" file.
6) "<ctrl>+d" views the previous "legal" word in the "words" file.

In AP releases 6.1.0 and higher, the spelling checker simply beeps to indicate the word was not found and does not interrupt the entry process.

The words used by the spelling checker are kept in the "dm,words," file.

The spelling checker uses the "speller", "speller-off", and "speller-on" verbs for checking or changing its current state. A "q-pointer" must be present in the current account md to the "dm,words," file and an index must be present on attribute 0 of the "dm,words," file. This q-pointer is usually provided to each new account automatically and can be found in the "dm,newac," file.
Syntax
Options
Example
Purpose
Related tcl.speller-on
filename.words
up.options.s
update.processor
up.z
tcl.speller
tcl.speller-off
up.zs
filename.newac
up.sc.a
up.sc.aa
up.sc.aaa
basic.access
up
updte.processor

up

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) }
up
u

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.

Paragraphs
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.
<Ctrl>+x+
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}{item.id}
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}item.id {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 }item.id <Ctrl>+m
Write the contents of the current item cut buffer to the item specified by item.id.


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}item.id <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}item.id <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}item.id <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 item.id attribute.list (options
up
u
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.
Syntax
Options
Example
Purpose
Related up.a
up.sc.a
up.sc.aa
up.sc.aaa
up.arm
up.arn
up.b
up.c
up.options.c
up.cc
up.cd
up.cl
tcl.compile-run
up.correlative
up.correlative.adi
up.cp
up.cr
cruising
up.cut.paste
up.cw
up.d
up.data-entry
up.delete.text
double.clutching
up.e
up.exit.item
up.f
up.g
up.h
hotkeys
up.i
up.options.i
access.id-prompt
up.input-conversion.adi
up.input-conversion.fdi
up.insert.mode
up.j
up.k
up.l
up.options.l
up.m
up.n
up.o
up.only
up.options
up.output-conversion.adi
up.overtype.mode
up.p
up.prestore
processing.codes
up.r
up.options.s
up.search.replace
tcl.spelling.checker
up.t
up.u
up.commands
update.processor
up.v
up.w
up.x
up.x0
up.x1
up.x2
up.x3
up.x4
up.x5
up.x6
up.x7
up.x8
up.x9
up.xb
up.xc
up.xe
up.xf
up.xi
up.xk
up.xl
up.xn
up.xo
up.xp
up.xr
up.xs
up.xx
up.y
up.z
up.znumber
up.za
up.zb
up.zc
up.zd
up.ze
up.zg
up.zh
up.zl
up.zn
up.zo
zooming
up.zp
up.zq
up.zr
up.zs
up.zt
up.zw
up.zy
up.zz
up.zx
up.macro
updte.processor

tcl.:ent-link

Command tcl.:ent-link Verb: Access/TCL
Applicable release versions: AP 6.1
Category TCL (746)
Description creates links and associations between entities in the system.
Links establish the communication path between entities in a given system. This command is the basic tool to create all sorts of association, or group of entities linked together. The TCL commands "tandem", "mirror", "converse" etc... are only special cases of useful associations. The ":ent-link" command is normally 'packaged' in more simple commands. It is not intended to be used routinely, since it is fairly complex.

cent Optional Controlling Entity ID. If specified, an association is created. The controlling entity MUST be a device (serial, telnet, etc..)

string Optional Termination String. If not specified, ESC'x' is used. The string can be expressed as any combination of characters (eg c'Ab'), hexadecimal values (eg x'1b') or decimal values, up to 4 characters, separated by commas (eg x'1b',c'x'). The string is associated to the controlling entity. When the controlling entity receives the termination string on its standard input, it terminates the association.

code Optional Association Code. This code is a decimal number from 1 to 255, which is given to the association as a mean of simple identification. The legal values are defined in the include "dm,bp,includes qcb.inc".

went Optional Wake up Entity ID. This entity must be a valid Pick process entity ID (eg P12). If specified, the entity (possibly the current process) is deactivated when the association is successfully created. When the association is terminated, the entity is awaken. This option is useful to wait for the termination of an association.

mid Optional Master Association ID. If specified, the association is attached to the Master Association as a 'sub-association'. If the master association terminates, all the sub-associations are also terminated.

t Type of a link. This one letter code is 'o' for an output link, and 'f' for a forwarding link.

eorg Entity ID of the origin of a link.

edest Entity ID of the destination link.


Links to be created in the association are specified by a series of pairs of entities, eg. 'o[p12,s12]. When the association is terminated, the links are restored to their initial state. Links enclosed in the 'undo list', eg. 'u[o[o12,BB f[p12,NULL] ]' are created when the association is terminated.
Syntax :ent-link {c[cent] {s[string]} {a[code]} {w[went]} {m[mid]}} {t[eorg,edest] { ... }} {u[ {t[eorg,edest] { ... }} ]}
Options
Example
:ent-link c[s0] o[p0,p1]
  Create a pipe between the the Pick process 0 and the Pick process 1. After 
this command is executed, data printed by the Pick process 0 is sent as input 
to the Pick process 1. The serial device 0, normally associated to the Pick 
process 0, is the controlling entity. Therefore, hitting ESC and 'x' 
on the terminal associated to the Pick process 0 will terminate the pipe.

 :ent-link o[p1,bb]
  Sent all output of the Pick process 1 to the byte bucket. This is a way of 
suppressing all output from a process. Note there is no controlling entity, 
therefore the link will be terminated only by explicitly linking  the output op 
'p1' to something else.
Purpose
Related general.entity
tcl.:ent-list

ue.007a

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"
Item-id of the binary item.

"item.body"
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.

"size"
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.

"code"
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.id^item.body,"u007A")
Options
Example
equ DLE to char(16)

x=char(01):DLE:"_"
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)

x=DLE:char(128+32):DLE:DLE
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.
Purpose
Related

pc.mt

Command pc.mt Processing Code/Restore Processor
Applicable release versions: AP, R83
Category Restore Processor (84)
Description invokes the time conversion function to convert external time representations to internal format or to convert internal time values to one of a variety of external time formats.

The "internal" time format is the number of seconds from midnight. The "external" time is 24-hour military format (e.g., 23:25:59) or 12-hour format (e.g., 11:25:59PM).

For input-conversion, the time is entered with 'AM' or 'PM' immediately following the numeric time. If none is entered, 'AM' is assumed. On output, 'AM' or 'PM' is always printed immediately following the numeric time.

Note: "12:00AM" is considered midnight. "12:00PM" is considered noon. 'AM' and 'PM' are ignored on input if the "mt" code is specified. Illegal values are converted to null on input.

When used as an input-conversion, the "mt" code validates the time and converts it to the internal format of seconds from midnight. When updating a field controlled by an "mt" conversion, the "/" (slash) character can be used to insert the current time into the attribute.

"h" specifies a 12 hour clock. Default is (military) 24 hour clock.

"s" includes seconds in output value. If "s" is omitted, seconds are not listed on output.
Syntax mt{{h}{s}}
Options
Example
data   conversion   ouput

3600     mt         01:00
3600     mth        01:00am
3600     mts        01:00:00
3600     mths       01:00:00am
46800    mt         13:00
46800    mth        01:00pm
3630     mts        01:00:30
46800    mths       01:00:00pm
Purpose
Related basic.iconv
external.format
internal.format
basic.conv.expression
basic.timedate
basic.time()
output-conversion
processing.codes
up.output-conversion.adi
up.input-conversion.adi
up.correlative.adi
pc

legal

Command legal Introductory/Access: Modifiers
Applicable release versions:
Category Access: Modifiers (8)
Description Copyright (c) 1993, 1994, 1995 by Pick Systems. All rights reserved. This book is protected by U.S copyright law and international treaties. Unauthorized reproduction or distribution of this book, or any portion of this book, is illegal and punishable to the fullest extent of the law.

While every precaution has been taken in the preparation of this publication, the information in this manual is subject to change without notice and should not be construed as a commitment by Pick Systems. The company assumes no liability for any errors or omissions in this manual.

TRADEMARK CREDITS

Advanced Pick (r) is a registered trademark of Pick Systems.

The Pick Operating System (r) is a registered trademark of Pick Systems.

The Pick System (r) is a registered trademark of Pick Systems.

FlashBASIC is a trademark of Pick Systems.

Pick/BASIC is a trademark of Pick Systems.

Access is a trademark of Pick Systems.

Update Processor is a trademark of Pick Systems.

Output Processor is a trademark of Pick Systems.

AIX and RISC System/6000 are trademarks of International Business Machines Corporation.

DG/UX is a trademark of Data General Corporation.

MS-DOS is a trademark of the Microsoft Corporation.

SCO (r) is a registered trademark of The Santa Cruz Operation, Inc.

UNIX (r) is a registered trademark of Unix System Laboaratories.

PRINTING HISTORY

The body of this document was created using the Update and Output processors and the Pick/BASIC capabilities of Advanced Pick.
First Edition, October, 1992
Second Edition (Version 1.0.4), July, 1993
Third Edition, December, 1993
Fourth Edition (Version 2.0), January 1995

COMMENTS

Comments may be sent to the publisher:
Pick Systems
1691 Browning Avenue
Irvine, CA 92714
Syntax
Options
Example
Purpose
Related