data.representation Definition/BASIC Program, runoff.pfile Command/Runoff: Commands, flash.basic.$log Definition/BASIC Program, basic.intro Introductory/BASIC Program, cfunc.read C Function/C Functions, cfunc.introduction Introductory/C Functions, tcl.:taskinit Verb: Access/TCL, tcl.addbi.apdos Verb: Access/DOS, tcl.list-obj Verb: Access/TCL, basic.% Function/BASIC Program, basic.system Function/BASIC Program, tcl.addbi.unix Verb: Access/Unix, attribute.defining.item.article Article/Article, tcl.@ Definition/TCL, basic.debugger.b Command/BASIC: Debugger, basic.debugger.c Command/BASIC: Debugger, flash.basic.notes Article/Article, cfunc.readv C Function/C Functions, data.management Introductory/Access: Modifiers, flash.basic.differences Definition/BASIC Program, compile.time.date.stamp.ap Definition/BASIC Program, basic.performance Definition/BASIC Program, tcl Introductory/TCL, tcl.setup-printer Verb: Access/TCL, ap.overview Article/Article, tcl.help Verb: Access/TCL, basic.quotes Reserved Character/BASIC Program, UE.4193 User Exit/PROC, basic.cfunction Definition/BASIC Program, signals Definition/Unix, basic.execute.unix Statement/BASIC Program, basic.execute.apdos Statement/BASIC Program, ap.dict.sub.calls Article/Article, basic.debugger.de Command/BASIC: Debugger, flash.basic.error.logging Definition/BASIC Program, tcl.rmbi Verb: Access/Unix, flash.basic Definition/BASIC Program, programming.using.up Article/Article, basic.retrieval.locks Definition/General, cfunc.load C Function/C Functions, preface Introductory/Access: Modifiers, tcl.dev-att Verb: Access/TCL, tcl.shpstat Verb: Access/TCL, cfunc.call C Function/C Functions, pc.ms Processing Code/Restore Processor, r83.to.ap.2 Article/Article, UE.6193 User Exit/BASIC Program, basic.@AM Function/BASIC Program

data.representation

Command data.representation Definition/BASIC Program
Applicable release versions: AP, R83
Category BASIC Program (486)
Description data types employed in Pick/BASIC.

There are primarily two types of data: numeric and string.

Numeric data consists of a series of digits and represents an amount, such as 123.

String data consists of a set of characters, such as "Jan Smith".

A numeric value in the range of: {+/-}140737488355327*(10(-p)) where "p" is the precision value between 0 and 9, is stored as numeric data. A numeric value outside this range is stored as string data.

In order to maintain maximum accuracy, when an operation causes an overflow condition, a precision of up to 18 digits to the right of the decimal is kept internally.

Results of addition (+), subtraction (-), division (/), and multiplication (*), and remainder (/) operations that exceed this range of {+/-}140737488355327*(10(-p)) have no limitation on their numeric range.

For the comparison operators such as less than (<), equal (=), greater than (>), and the arithmetic functions int(x), abs(x), mod(x,y), and rem(x,y), there is no limitation, since the result is limited to a 1 or 0.

The Pick/BASIC functions "ln", "sqrt", "pwr", and "exp" can be as large as
(+/-)140737488355327x(10(-p)).

A string may contain up to 2 gigabytes of characters in Advanced Pick. A string constant is represented by a set of characters delimited by single quotes ('), double quotes ("), or backslashes (). If any of the string delimiters are to be part of the string, then one of the other delimiters must be used to delimit the string.

Numeric and string data may be represented within the Pick/BASIC program as either constants or variables. A constant, as its name implies, has the same value throughout the execution of the program. A variable may contain data types other than string and numeric data (root, active list, file.variable), but these representations are limited to specific statements.
Syntax
Options
Example
Purpose
Related basic.assignment
active.list
basic.logical.expressions
basic.ac.expression
basic.file.variable

runoff.pfile

Command runoff.pfile Command/Runoff: Commands
Applicable release versions: AP, R83
Category Runoff: Commands (93)
Description creates a separate Spooler entry containing the table of contents created with the ".contents" command.

Directs subsequent output to the specified "print.file.number", just like the "print on" statement in Pick/BASIC.
Syntax .pfile print.file.number
Options
Example
Purpose
Related runoff.contents
runoff.commands
basic.print.on

flash.basic.$log

Command flash.basic.$log Definition/BASIC Program
Applicable release versions: AP 6.0 FlashBASIC
Category BASIC Program (486)
Description records compilation errors while compiling a Pick/BASIC program with FlashBASIC. See "FlashBASIC error logging" for more information.
Syntax
Options
Example
Purpose
Related flash.basic.error.logging

basic.intro

Command basic.intro Introductory/BASIC Program
Applicable release versions: AP 6.2
Category BASIC Program (486)
Description a high-level programming language, is the principal programming language bundled with the Pick System and was designed for the implementation of application requirements not handled by standard Pick functionality.

Pick/BASIC source can contain any number of statements in any order and can be stored as programs or subroutines called by other programs or processing codes. Pick/BASIC programs are created in the user's editor of choice and reside as items within a file. Prior to execution, the programs must be compiled to convert the program into object code. Compiled programs are stored in the dictionary of the file that contains the source code. Compiled programs or subroutines can be cataloged as verbs withing the users master dictionary (Refer to the TCL commands compile, catalog, decatalog, and run).

Program Statements

A Pick/BASIC program is composed of statements made up of Pick/BASIC commands, variables, constants, expressions, and functions. Pick/BASIC statements may contain arithmetic, relational, and logical expressions. These expressions are formed by combining specific operators with variables, constants, or Pick/BASIC intrinsic functions. The value of a variable may change dynamically throughout the execution of a program. A constant, as its name implies, has the same value throughout the execution of a program. An intrinsic function performs a pre-defined operation on a supplied parameter(s).

Normally, within a Pick/BASIC program, the programmer writes only one statement per line. This is done for the ease of reading and tracking of logic. More than one statement can be placed on a program line by separating them with semicolons. Statements which end with "then" or "else" on a line create a block or multiline structure. See the "then/else" entry for details on the "then ...else" statements.

Labels may be placed at the beginning of any Pick/BASIC statement. A statement label may be numeric or alphanumeric. If it is alphanumeric, it must begin with a letter and may be any combination of letters, numbers, periods, or dollar signs and can end with an optional colon. The colon is also optional with a numeric label. Refer to the entry "statement labels".
Except for situations explicitly called out in the following sections, blank spaces appearing in the program line which are not part of a literal are ignored. Blank spaces and lines may be used within the program for purposes of appearance.

Data Representation

There are two types of data used in Pick/BASIC: numeric and string. Numeric data consists of a series of digits and represents an amount, such as 255. String data consists of a set of characters, such as Jan Smith. Refer to the entry data representation for more information.

Variables

Variables are values that can change. Values can be assigned with an assignment statement. Assignment statements assign the value of an expression to a variable. A variable can be a simple variable, an array element, a dynamic array element, or a substring. For example:

var=x+2

assigns the value of the expression x+2 to the variable var. Refer to the entry assignment for more information about assignment statements.

Arrays

An array is a table of values of any data type. Each value in an array is called an element. The elements in an array are ordered allowing each array element to be accessed by specifying its position within the array.

Pick/BASIC supports two types of arrays: dynamic arrays and dimensioned arrays. Dimensioned arrays can be defined with the dim statement, which specifies the name of the array and the number of elements in the array. Or, dimensioned arrays can be defined with the file statement.

Dimensioned arrays are limited to two dimensions (rows and columns). Additional dimensions can be obtained by referencing dynamic arrays from elements in a dimensioned array.

A dynamic array is a string containing attribute marks, value marks, and/or subvalue marks which are used as field delimiters. All elements within dynamic arrays are separated by one of these delimiters. Dynamic arrays do not have a fixed size nor are they dimensioned. Subscripts in dynamic arrays are enclosed in angle brackets (<>). They are called dynamic because the number of elements can be increased or decreased automatically by the system without the programmer needing to recompile the program.

In most cases, accessing a dimensioned array is faster than accessing the same size dynamic array. A dynamic array may be an element in a dimensioned array, in which case the dynamic array subscripts are specified following the dimensioned array subscript. Refer to the entries array, dimensioned array, and dynamic array for more information about arrays.

Operators

Expressions are formed by combining operators with variables, constants, or functions. When an expression is encountered as part of a Pick/BASIC program statement, it is evaluated by performing the operations specified by each of the operators on the adjacent operands.

Each operator has a precedence rating and, in any given expression, the highest precedence operation is performed first. (0 is the highest precedence and 8 is the lowest. If there are two or more operators with the same precedence or if an operator appears more than once, the leftmost operation is performed first. Precedence of the operators is as follows:

Operator Operation Precedence
( ) Express evaluation 0 -- highest
[ ] Substring extraction 0
^ ** Exponent 1
- Unary minus 2
* Multiplication 3
/ Division 3
+ Addition 4
- s Subtraction 4
expr expr Format string 5
cat (:) Concatenate 6
= < > # Relational operators 7
<> ><
<= >=
match Pattern matching 7
and & Logical operators 8 -- lowest or !

Parentheses may be used anywhere to clarify evaluation, even if they do not change the order. The parenthesized expression as a whole has highest precedence and is evaluated first. Within the parentheses, the rules of precedence apply.

The function associated with the *=, +=, -=, /= assignment statements take place after all left side operations and before the assignment.

Refer to the individual entries for each operator and the entries logical operators, operators, pattern matching, precedence, relational operators, and special characters.

Arithmetic Operators

Arithmetic expressions are formed by using the arithmetic operators. The simplest arithmetic expression is a single numeric constant, variable, or function. A simple arithmetic expression may combine two operands using an arithmetic operator. More complicated arithmetic expressions are formed by combining simple expressions using arithmetic operators.

If a string value containing only numeric characters is used in an arithmetic expression, it is evaluated as a decimal number. If a string value containing non-numeric characters is used in an arithmetic expression, a warning message is printed and zero is assumed for the string value.

Format Strings

Numeric and non-numeric strings may be formatted using format strings, which consist of numeric masks and format masks. The numeric mask code controls justification, precision, scaling, and credit indication. The format mask code controls field length and fill characters.

The entire format string is enclosed in quotation marks. If a format mask is used, it should be enclosed in parentheses within the quotation marks. The entire format string may be used as a literal, or it may be assigned to a variable. A format string literal can immediately follow the string it is to format. A format string variable must be separated by at least one space from the string it is to format. The format string may also be used directly in conjunction with the print statement. For more information, refer to the entry masking.

String Expressions

A string expression can be a string constant, a variable with a string value, a substring, or a concatenation of string expressions. String expressions may be combined with arithmetic expressions.

Concatenation of strings is specified by a colon (:) or by the operator cat. The operator cat must be preceded and followed by blanks. Refer to the entry string expressions.

Substrings

A substring is a set of characters that makes up part of a whole string. The syntax to specify a substring is:

substring = string[m,n]

where "string" is a string variable, "m" is the starting character position, and "n" is the substring length. For example, if the current value of variable S is the string "ABCDEFG", then the current value of S[3,2] is the substring "CD" (the two-character substring starting at character position 3 of string S).

If the starting character specification is past the end of the string value, then an empty substring value is selected. If the starting character specification is negative or zero, then the substring is assumed to start at character one.

If the substring length specification exceeds the remaining number of characters in the string, then the remaining string is selected. If the substring length specification is negative or zero, then an empty substring is selected.

A segment of a character string may be changed or substituted without affecting the remainder of the string by assigning the new segment to the variable containing the original string. The new segment is assigned to the original string variable with the starting character and segment length specified with the variable. The string variable may be a single variable or an array element. For example, if the current value of the variable S above ("ABCDEFG") is to have characters 3 to 5 inclusive replaced by the string "123" the assignment S[3,3]="123" accomplishes this substitution so that the variable S now becomes "AB123FG". The general syntax for substring replacement is:

string[m,n] = substring

where "string" is a string variable, "substring" is the substring to be inserted, "m" is the starting character position, and "n" is the number of characters in the string which are replaced. See the Advanced Pick Reference Manual "substring assignment" token for more details.

One or more fields or substrings within a character string variable which are delimited by a specific character can be changed by a single assignment.

string[delimiter,m,n] = substring (s

where "string" is a string expression or variable, "substrings" is one or more substrings (separated by a delimiter) to be substituted, "delimiter" is the delimiter separating fields or substrings in the original string, "m" is the starting field position within the string for the substring to be placed, and "n" is the number of fields or substrings to be replaced.

If m is less than 1, 1 is assumed. If m is greater than the number of fields within string then the number of fields in string is increased by adding null fields separated by the delimiter so that string has the length of m fields. Multiple substrings separated by the specified delimiter can be substituted in the original string.

The expression n has different effects depending on whether it is positive, negative or zero. If it is positive, then n fields in string are replaced with n substrings. If m + n is greater than the number of fields in string, then the number of fields in the resulting string is increased to the value m + n, and the extra substrings are concatenated to the end of the original string. If m + n is less than the number of fields in string but n is greater than the number of substrings specified, only the specified substrings are substituted and the remainder of the n fields in string are nulled.

If n is zero, then no fields in string are deleted and the specified substring(s) are inserted into string before the mth field. If n is less than zero, then n fields greater than or equal to m are deleted from string and the entire expression containing the substring(s) is inserted at that point in the string.

Relational Expressions

A relational expression evaluates to 1 if the relation is true, and evaluates to 0 if the relation is false. Relational operators have lower precedence than all arithmetic and string operators. Therefore, relational operators are only evaluated after all arithmetic and string operations have been evaluated.

If one operand is numeric and one operand is string, both operands are treated as strings. To resolve a numeric relation, the values of the expression are compared. To resolve a string relation, the characters in each string are compared one at a time from leftmost characters to rightmost. If no unequal character pairs are found, the strings are considered to be equal.

If the two strings are not the same length, and the shorter string is otherwise identical to the beginning of the longer string, the longer string is considered greater than the shorter string.

The resolution of unequal character pairs depends on the characters. If the unequal pair of characters are non-alphabetic characters, the characters are ranked according to their numeric ASCII code equivalents. The string contributing the higher numeric ASCII code equivalent is considered to be greater than the other string. If the unequal pair of characters are letters of the alphabet, the pair is ranked in strict alphabetical order.

If one of the characters is a letter of the alphabet and the other character is non-alphabetic, the characters are ranked according to the numeric ASCII value of the uppercase letter, even if the letter is in lowercase, and the numeric ASCII value of the non-alphabetic character.

Arrays and Relational Expressions

Elements of dimensioned and dynamic arrays can be compared in relational expressions using the standard syntax. In addition, all elements of the array can be compared to a specified value by using an asterisk (*) to identify the element. In multi-dimensioned arrays, one or more dimensions can be specified using the example.

When the asterisk is used, the operators < > = <= >= # return a true value if at least one element of the array satisfies the relation. The asterisk may be specified only in relational expressions and only in one array expression in a statement.

Match - Pattern Matching Operator

string.variable match pattern

The match operator compares a string value to a predefined pattern and evaluates to 1 (true) or 0 (false). The pattern may consist of any combination of the following:

pattern operation
nn tests for n integers.
na tests for n alphabetic characters.
nx tests for n characters of any type.
'string' tests for literal string (double quotes are used when testing for a literal string in combination with the above patterns).

If n is 0, the relation evaluates to true only if all the characters in the string conform to the specified data type. The character n tests only for integers; +, -, and . are not considered to be numeric.

Logical Expressions

Logical expressions (also called Boolean expressions) are the result of applying logical (Boolean) operators to relational or arithmetic expressions.

Logical operators work on the true or false results of relational or arithmetic expressions. (Expressions are considered false when equal to zero, and are considered true when non-zero.)

Logical operators have the lowest precedence and are evaluated after all other operations have been evaluated. If two or more logical operators appear in an expression, the leftmost is performed first.

Logical operators act on their associated operands as follows:

a OR b is true (evaluates to 1) if a is true or b is true.

a ! b is false (evaluates to 0) if a and b are both false.

a AND bis true (evaluates to 1) only if both a and b are true.

a & b is false (evaluates to 0) if a is false or b is false or both are false.

Retrival and Update Lock Codes

If a Pick/BASIC program is executed by a user who does not have retrieval and/or update privileges for a file that does and is opened in the program, and then attempts to read and/or write to such a file, this will result in termination of the program with an error message. In order to read or write to such a file, users must make sure that the retrieval and update lock codes match those of the file that is opened. This is a system function and cannot be accomplished from Pick/BASIC. If the file is retrieval protected, the file cannot be opened and the program will be terminated with an error message; see the Security Section.

Pick/BASIC Statements

The following is a list of Pick/BASIC statements. For more detailed information about these statements, refer to their individual entries in the body of Advanced Pick Reference Manual.

* ! abort
assigned aux begin
block break
call capturing casing
chain chap (6.2) clear
clearfile clearselect (6.2) close
common convert crt
data debug del
delete dim echo off
echo on else end
end case enter equ{ate}
execute exit file
footing for.. next
for next .. until for next .. while get
gosub go{to} heading
hush (6.2) if..then..else in
{$}include input inputclear
inputparity (6.2) inputnull (6.2)
inputtrap ins insert
key let locate
lock locked log
loop loop ..until loop ..while
mat matbuild matparse
matread{u} matwrite{u} next
null on gosub on goto
onerr open out
page precision print
print on printer close printer off
printer on procread procwrite
program prompt read{u}
readnext readt readtl
readtx readv{u} release
rem repeat replace
return returning return to
rewind root rqm
select send sleep
setting shift spoolq (6.2)
stop
subroutine tcl tclread
then..else unlock waiting
weof write{u} writet
writev{u} unblock (6.2)

Pick/BASIC Functions

The following is a list of Pick/BASIC functions. For more detailed information about these functions, refer to their individual entries.

@ functions % functions abs
access alpha ascii
assigned change (6.2) char
col1 col2 convert
cos count date
dcount delete dquote (6.2)
dtx ebcdic ereplace (6.2)
error exchange (6.2) exp
extract field fmt (6.2)
fold iconv index
insert inmat (6.2) int
len ln maximum (6.2)
mod not num
occurs oconv pwr
rem replace rnd
scan (6.2) sentence (6.2) seq
sin sort soundex
space spooler (6.2) squote (6.2)
sqrt str summation (6.2)
sum swap (6.2) system
tan time timedate
trim xtd

Pick/BASIC Symbolic Debugger

The Pick/BASIC Symbolic Debugger facilitates the debugging of new Pick/BASIC programs and the maintenance of existing Pick/BASIC programs. The Pick/BASIC debugger requires sys2 privileges and has the following general capabilities:

- Step through execution of program in single or multiple steps.
- Transfer to a specified line number.
- Break execution at specified line numbers or when specified logical conditions have been satisfied.
- Display and/or change any variables, including dimensioned variables.
- Trace variables.
- Enter the system debugger.
- Direct output to either terminal or printer.
- Display and/or pop GOSUB stack.
- Display source code lines.

The Pick/BASIC debugger may be entered at execution time under the following conditions:

- The <break> key is pressed.
- The d (debug) option is specified with the run verb.
- The debug statement is executed in the program.
- A runtime error is encountered (unless the a (abort) option of the run verb is selected).
- The abort statement is executed in the program.
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. The symbol table 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. 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. Multiple symbol tables allow programmers to set up different break points and/or variable traces for different subroutines.

Pick/BASIC debugger commands are listed below. For more detailed information about each command, refer to it's entry.

b Establish a break point condition.
c Toggles source line display on and off.
d Display breakpoint and trace tables.
debug Escape to system debugger.
e Execute a specified number of lines.
end End program execution and return to TCL.
g Begin program execution at a specified line.
j Executes next line, displays next line if "c" option enabled.
k Remove a specified breakpoint.
l Display specified source lines.
l* Display all lines.
lp Toggle output device between terminal and printer.
n Execute through a specified number of breakpoints.
off Logs the user off the system.
p Inhibit display of program output.
pc Close output to spooler.
r Pop the top element off the gosub stack.
s Display the gosub stack.
t Set trace for a specified variable .
u Remove a specified trace.
$ Verify object code.
v Verify object code.
/var Print value of a specified variable.
/arr(m) Print value of a specified array element.
/* Print value of entire symbol table.
[] Display specified number of characters.
? Show the current program name, line number, and verify the program.

The following debugger commands are available from FlashBASIC:

down Move down the command stack.
edit Use the Update processor to edit the current program.
help Show the debugger commands.
up Move up the command stack.
?! show the current command stack and parameters.
Syntax
Options
Example
Purpose
Related

cfunc.read

Command cfunc.read C Function/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description equivalent to the Pick/BASIC statements depending upon type: read, readu, readu locked

type Pick/BASIC statement

_CP_READ read result from expression,string

_CP_READU readu result from expression,string

_CP_READUL readu result from expression,string locked value = 1 else value = 0

If value is not needed, the user may pass (int*) 0.

The _CP_read call uses the same optimized read routine as FlashBASIC which, from the 6.1 release onwards, is about 2-5 times faster than that which is used by Access and standard Pick/BASIC.

The expression should be an integer file descriptor returned by the _CP_open call.

This function returns -1 if an error occurs. The error code is contained in _CP_errno.
Syntax int _CP_read(int type, CPSTR** result, int expression, CPSTR* string, int* value)
Options
Example
The following example reads the item "myid" from "myfile".

CPSTR * s = _CP_mkstr("myfile");
CPSTR * id = _CP_mkstr("myid");
CPSTR * xx = _CP_str_null;
int f;

_CP_open(&f,_CP_str_null,s);
_CP_read(_CP_READ, &xx, f, id, 0);
Purpose
Related cfunc.introduction
cfunc.write
cfunc.writev

cfunc.introduction

Command cfunc.introduction Introductory/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description outlines how to access the Pick environment from the "C" programming language.

The functionality of the Pick environment is available from the C programming language. This is made available through a set of functions and macros defined in the include file "CPuser.h".

Library Format

Functions within the library have the following general structure:

{rc=}_CP_xxx({arg0{,arg1{,...}}});

where:

_CP_xxx is a general pattern for the name. It is always prefixed with _CP_ to avoid naming conflicts with standard libraries and is suffixed with an entirely lower-case tag like _CP_execute. Macros are provided using the same model, but they use uppercase tags like _CP_SLEN.

arg0 - argi are arguments.

rc is the result code. Almost all functions return an integer result. This result is -1 if an error occurs, and the global variable _CP_errno is set to one of the following error codes:

PE_NFILE Not enough memory to open more files
PE_ACCESS Cannot access file
PE_TRUNC String trunctated due to lack of memory
PE_NOSPACE Could not allocate workspace
PE_LOCK Item is locked
PE_INVAL Invalid call
PE_NONUM Not a number
PE_BADF File not opened
PE_MISSING File not found
PE_CONV Conversion error
PE_BADATTR Bad attribute
PE_TMOUT Input time out
PE_TAPE Tape error
PE_PROC Proc read error
PE_EOF End of file/item
PE_CALLMAIN Tried to call a main as a subroutine
PE_NOTROOT Bad root variable
PE_ILL_KEY Bad key operator
PE_LONG_STR Too long a string for heading
PE_LEVEL Debugger entered
PE_DEBUG Debugger entered
PE_BAD_PARAMS Too many parameters on a call
PE_LOAD_ERR Unable to load Flash subroutine
PE_END_LIST No more items on select
PE_GETSEND Bad pib on get/send
PE_MISCERR Miscellaneous logon error
PE_INIT Virtual machine not booted or attached
PE_BADUSER Bad user ID or user password
PE_BADMD Bad MD or MD password

General Usage

To use this library, the user makes a call to _CP_logon() at the beginning of the C program to connect to the Pick virtual machine. This call goes through the normal Pick logon activities, but suppress all user prompts and messages. Note that neither the user nor the MD macro will be executed. After logging on, the user has full access to the Pick database using C calls which provide functionality previously available only through Pick/BASIC. When the C program completes, the user must issue a _CP_logoff() call to terminate the Pick connection.

String Handling

The standard C string type is not sufficient for handling the dynamic nature of Pick strings, so a hybrid data type has been created called CPSTR. This data type provides allocation, deallocation, and resizing of strings at a much higher performance level than that obtained using malloc(), and free() with C strings. The internal structure of a CPSTR is reserved and SHOULD NOT BE ACCESSED DIRECTLY. Failure to abide by this rule will DEFINITELY GUARANTEE INCOMPATIBILITY WITH FUTURE RELEASES. The structure of a CPSTR is as follows:

Header Internal use only - DO NOT MODIFY
String - Character array containing the actual string
Terminator - A single character used for termination
Footer Internal use only - DO NOT MODIFY

The following macros are provided to access all desired portions of a CPSTR structure.

_CP_SLEN(s) returns the current length of a string. This length does not include any terminating character like a segment mark or a null character.

_CP_SADDR(s) returns a (char *) to the actual string data which may or may not be terminated by a 0x00. Note that this (char *) MUST NOT be passed to the free() C function or to any C function which may try to use free() on the (char *).

Allocation of CPSTR strings is accomplished via special allocation routines. CPSTR strings MUST NOT be allocated with the C function malloc(). The allocation routines provided set necessary internal flags, and they are much more efficient than malloc. Note that these routines create dynamic structures which must be deallocated with the routines listed below.

_CP_str_alloc(l) returns a CPSTR of length l. The actual string data portion of the string is undefined.

_CP_mkstrl(char *s, int l) Returns a CPSTR from a C string s, of length l. The string portion of the CPSTR will contain a copy of the C string's data.

_CP_mkstr(char *s) Returns a CPSTR from a C string s terminated by a 0x00. The string portion of the CPSTR will contain a copy of the C string's data. This function is less efficient than _CP_mkstrl as it must scan the C string to determine its length.

_CP_str_realloc(CPSTR **s, int l) Resizes the CPSTR s.

_CP_str_free(CPSTR ** s) Frees the desired string s.

Note that when the _CP_logoff call is executed, all CPSTR's remain valid, but they may not be passed to any of the _CP_ routines. All CPSTR's are properly cleaned up when the C program exits.

The user must be careful with termination. Any _CP_ routine may modify the termination character. Therefore, the user must use the _CP_TERM() macro to terminate CPSTR's with a 0x00 if it is necessary to pass the string portion of it to a standard Unix routine.

Note that it is necessary to free strings only when the user has finished with them completely. All resizing of strings is accomplished automatically by the _CP_routines. For example, if a process repeatedly reads data into a buffer via the _CP_read call, this buffer will be automatically resized to fit the new data within the _CP_read call at every read.

Environment Setting

To make it easier to handle the differences between the standard behavior of Unix programs and the standard behavior of Pick programs, two calls are provided that set the "environment" to either Pick or Unix.

_CP_pick_env() sets the application to a standard "Pick" environment. When using this setting, all terminal input and output must be done via Pick routines ONLY.

_CP_unix_env() sets the application to a standard "Unix" environment. With this setting, all terminal input and output must be done directly from "C". The program must not "execute" or "call" any Pick routines which may "crt" or "print" something through Pick.

The original logon to Pick calls _CP_pick_env(). After that, the user may use these routines to switch environments as often as desired, but the environment functions are fairly expensive so they should only be used when switching environments is absolutely necessary. To ensure the correct functionality of the Unix shell, the system automatically calls _CP_unix_env() when the user logs off the of the Pick virtual machine.

Break Key Handling

When logged into Pick, the default action for the break key is set to push a level or drop into the debugger as is standard in Pick. This behavior may be changed however by using the following calls:

_CP_unix_break() causes the break key to force a logoff from Pick and terminate the C program with an exit() call. This simulates the standard behavior of the break key in a Unix application.

_CP_pick_break() causes the break key to behave in the Pick manner.

Handling General Pick Interrupts

Pick interrupts, besides breaks, such as messages, may not be masked, but they may be detected (after the occurence) by interrogating the _CP_interrupt variable. This integer location contains the same information available in BASIC from the system(37) function. However, examination of _CP_interrupt is much more efficient when programming in C.

Custom Signal Processing

The Pick libraries make extensive use of signal processing. Because of this, the practice of reprogramming signals within a C application using Pick C routines is strongly discouraged. However, if it is absolutely necessary, there are several rules which must be followed.

When calling _CP_logon, all signals are re-routed to Pick signal handlers.

When calling _CP_logoff, all signals are re-routed to Unix defaults. Note that they are not necessarily reset to the values they held before the _CP_logon call.

The signal SIGUSR2 must never be reprogrammed as it is used by Pick for logging off and sending messages.

Because interrupts may occur within critical code, the user may not make calls to _CP_ functions within signal handlers.
Syntax
Options
Example
The following program prints the name of all users in the users file.

#include "CPuser.h"

main()
{
  CPSTR * machine = _CP_mkstrl("pick0",5); /* default */
  CPSTR * user = _CP_mkstrl("dm",2);
  CPSTR * md = _CP_mkstrl("dm",2);

  CPSTR * filename = _CP_mkstrl("users",5);
  int     fd = -1;
  int     sl = -1; /* initialize select list */

  CPSTR * item_id = _CP_str_null;

/* Logon onto "pick0" as "dm" in the "dm" md */

  if (_CP_logon(machine, user, _CP_str_null, 
      md, _CP_str_null, -1, 0) < 0)
  {
    printf("Logon error %dn", _CP_errno);
    exit(1);   
  }

  /* done with machine, user, and md */

  _CP_str_free(machine);
  _CP_str_free(user);
  _CP_str_free(md);

  /* Make the break key terminate the program */

  _CP_unix_break();

  /* Open the users file into the file descriptor fd */

  if (_CP_open(&fd, _CP_str_null, filename) < 0)
  {
    _CP_logoff();
    printf("Could not open users file n");
    exit(2);
  }

  /* done with filename */

  _CP_str_free(filename);
  
  /* Do a raw select of "users" and store that select
     list in the select list descriptor sl */

  _CP_select(fd, &sl, 0);

  /* Switch to Unix-type I/O so we can use printf */

  _CP_unix_env();

  /* repeatedly read item-ids and print them as a list */

  /* Note how item_id is repeatedly passed to _CP_readnext.
     Each time, _CP_readnext will resize it if necessary,
     and write the next item-id into that CPSTR  */

  while (_CP_readnext(&item_id, &sl, 0, 0) >= 0)
  {
    _CP_TERM(item_id); /* terminate for printf */
    printf("%sn", _CP_SADDR(item_id));
  }

  /* done with item_id - Not absolutely necessary since */
  /*   it will be cleaned up when we exit               */

  _CP_str_free(item_id);

  /* logoff and return */

  _CP_logoff();
  return 0;
}
Purpose
Related cpstr*
cfunc.alpha
cfunc.ascii
cfunc.ati
cfunc.at2
cfunc.break
cfunc.call
cfunc.casing
cfunc.cat
cfunc.clearfile
cfunc.close
cfunc.col1
cfunc.col2
cfunc.compare
cfunc.convert
cfunc.count
cfunc.crt
cfunc.crtn
cfunc.data
cfunc.date
cfunc.dcount
cfunc.debug
cfunc.delete
cfunc.delete_item
cfunc.dtx
cfunc.ebcdic
cfunc.echo
cfunc.execute
cfunc.extract
cfunc.field
cfunc.field_store
cfunc.fold
cfunc.footing
cfunc.get
cfunc.heading
cfunc.iconv
cfunc.in
cfunc.index
cfunc.insert
cfunc.interrupt
cfunc.key
cfunc.load
cfunc.locate
cfunc.lock
cfunc.logon
cfunc.match
cfunc.mkstr
cfunc.mkstrl
cfunc.num
cfunc.occurs
cfunc.oconv
cfunc.open
cfunc.out
cfunc.ovly_subs
cfunc.page
cfunc.page_n
cfunc.pick_break
cfunc.pick_env
cfunc.print
cfunc.printer
cfunc.printn
cfunc.print_on
cfunc.prompt
cfunc.read
cfunc.readnext
cfunc.readt
cfunc.readv
cfunc.release
cfunc.release_all
cfunc.replace
cfunc.replace_bridge
cfunc.rewind
cfunc.root
cfunc.saddr
cfunc.select
cfunc.send
cfunc.sleep
cfunc.slen
cfunc.sort
cfunc.soundex
cfunc.space
cfunc.str
cfunc.str0
cfunc.str_alloc
cfunc.str_free
cfunc.str_null
cfunc.str_realloc
cfunc.substr
cfunc.sum
cfunc.system
cfunc.term
cfunc.time
cfunc.timedate
cfunc.trim
cfunc.unix_break
cfunc.unix_env
cfunc.unlock
cfunc.unlock_all
cfunc.weof
cfunc.write
cfunc.writet
cfunc.writev
cfunc.xtd
cpstr
cfunc.integration
cfunc.precision
cfunc.rs
cfunc.sr
cfunc.si
cfunc.is
cfunc.str_copy
cfunc.filelock
cfunc.fileunlock
cfunc.trans
cfunc.clearselect
cfunc.build_msg
cfunc.out_msg

tcl.:taskinit

Command tcl.:taskinit Verb: Access/TCL
Applicable release versions: R83
Category TCL (746)
Description pre-allocates extra workspaces for use by the "execute" statement in Pick/BASIC. This is not needed in Advanced Pick, since workspaces are assigned on the fly.

The "number.workspaces" parameter indicates the number of process workspaces to pre-assign per port.

The optional "max.depth" parameter indicates the maximum nesting depth. The default is 7.

As the workspace size is fixed in R83, increasing the "max.depth" reduces the remaining space available for the "execute" processes.

This command can be useful to recover disk in the event of running out of disk space by using "0" (zero) as the number of workspaces. Any workspaces already assigned will be returned to the overflow table.

Each workspace takes up about 400 frames:

number of ports * number workspaces * 400 = frames used
Syntax :taskinit number.workspaces{,max.depth}
Options
Example
Purpose
Related tcl.link-ws
basic.execute
port.number

tcl.addbi.apdos

Command tcl.addbi.apdos Verb: Access/DOS
Applicable release versions: AP/DOS
Category DOS (25)
Description extends the Monitor functionalities by adding new C functions, available to Pick/BASIC.

The "addbi" command adds the specified list of user-defined C-functions to the list of built-in functions that are in the MS-DOS "initfncs.c" file and the Pick "c.builtin" item.

"function.list" is a list of one or more item-id's (separated by spaces) of functions to be added to the existing built-in functions. If "function.list" is omitted, a previously generated select list can be used. (see "select" and the related list-handling verbs).

If "function.list" is omitted and no active list is present, the MS-DOS "initfncs.c" file is rebuilt to match the list of built-in functions. Up to 255 user-defined functions may be added.

Built-in functions are defined in the item "c.builtin" item located in the "dm,messages," file. When invoked, "addbi" updates this item and updates the C module "initfncs.c". When compiled and linked with the supplied mixed language interface object modules, "initfncs.c" creates a customized "PICKCSUP.EXE" executable file.

The added functions can then be called directly from Pick/BASIC. See "c function".
Syntax addbi { function.list }
Options
Example
Purpose
Related tcl.listbi
tcl.rmbi
basic.cfunc
tcl.set-cmem
basic.cfunction
basic.cfunc.user
tcl.addbi.apdos.link

tcl.list-obj

Command tcl.list-obj Verb: Access/TCL
Applicable release versions: AP 6.1
Category TCL (746)
Description outputs descriptive internal information about programs compiled for Pick/BASIC and FlashBASIC.

Without any options the "list-obj" verb will output information on the "bp" file.

The displayed information includes the last compile date, last compile time, total frame usage, port number last compiled on, user name who last compiled, and account where last compiled.
Syntax list-obj {file.reference}
Options e outputs Pick/BASIC frame usage, FlashBASIC frame usage, total frame usage, beginning fid, and release version last of last compile.
p directs output to the Spooler
Example
Purpose
Related compile.time.date.stamp.ap
ue.222d
access.c/total
access.c/code
access.c/options
access.c/bytes
access.c/flash
access.c/fid
access.c/size
access.c/date
access.c/time
access.c/port
access.c/user
access.c/acct
access.c/release

basic.%

Command basic.% Function/BASIC Program
Applicable release versions: AP/Unix, AP/DOS
Category BASIC Program (486)
Description the first character of a built-in C function called from Pick/BASIC.
Syntax
Options
Example
Purpose
Related basic.cfunc
basic.cfunc.user
tcl.addbi.unix

basic.system

Command basic.system Function/BASIC Program
Applicable release versions: AP, AP 6.2, R83
Category BASIC Program (486)
Description provides an interface to a number of system variables, depending upon the requested numeric argument, as shown below:

0 Context-oriented status information.

After a tape-handling error, system(0) returns:

1 if not attached.
2 null variable.
3 attempt to write null string.
5 EOT encountered.
6 tape write protected.
7 tape unit not ready.
8 unrecoverable parity error.
9 block transfer error.
10 binary item read (see note below).
11 record truncated.
12 unrecoverable write error.
13 unrecoverable read error.
14 no tape media inserted.
15 tape subsystem not ready.

After a "readu", "readvu" and "matreadu" statement which contains a "locked" clause, system(0) returns the port.number that has the item locked.

Value 10 actually has nothing to do with tape and is relevent to all "read"-type statements. It is set when an "indirect" (or "pointer") item is read.

On AP/Unix implementations, system(0) returns the value of "errno" after a C function call. On 6.2 and above, this is no longer supported and system(41) should be used instead.

All statements which allow the "onerr" clause provide a "hook" to system(0). See "onerr" for examples.

1 Returns 1 if the system printer is "on", meaning that a "printer on" statement has been issued or that the program was activated with a (p) option. Otherwise, a 0 (zero) is returned, meaning that output is being directed to the terminal.

2 Returns the current output device page width as defined by the "term" command.

3 Returns the current output device page length as defined by the "term" command.

4 Returns the number of lines remaining to print on the current page, based on the current terminal characteristics previously defined with the "term" command.

5 Returns the current page number.

6 Returns the current line number (Not the "port" number -- the actual print line number).

7 Returns the terminal "type" code, as defined by the "term" command.

8 Returns the block size at which the tape was last attached.

9 Returns the current cpu millisecond count.

10 Checks the current stack (ston) condition. Returns 1 (one) if the stack is on, or 0 (zero), if not.

11 Checks for an externally-generated active list.

In R83, it returns "0" if there is no active list, or "1" (one) if an active list exists.

In AP, it returns "0" if there is no active list, or "n" (the actual number of items selected), if an active list exists.

This has nothing to do with the internal (Pick/BASIC) "select" statement, which requires a "readnext" to determine if any items were selected. See the "readnext" and "select" statements for additional warnings on using system(11).

12 Returns the system time in milliseconds.

13 Forces an rqm (terminates timeslice) and returns a 1. Deactivates the process in the scheduling queue until its next turn.

14 Returns the number of bytes in the terminal type-ahead input buffer.

15 Returns the TCL verb option{s} that are in effect.

16 Returns the current process level.

17 Returns the message numbers (item-ids) returned by the previous "execute" statement, separated by attribute marks.

18 Returns the number of ports on the system.

19 Returns a unique item-id consisting of the current system date in internal format, followed immediately by the current system time in seconds. If more than one item-id is generated in a second, an alpha character is appended to the item-id.

20 Returns the most recent Spooler entry number generated by the current process.

21 Returns today's date in internal format with a sequential numeric suffix.

22 Returns the port.number of the current process.

23 Returns the current process privilege level. (In R83, this returns 1 if the current process has a "sys2" privilege level, otherwise it returns 0 (zero).)

24 Returns 1 if the current process is a phantom. Otherwise it returns 0 (zero).

25 Checks for an active secondary list. Returns the number of items in the secondary list, or 0 (zero) if no secondary list is active.

26 Returns 1 if "capturing on" is in effect. Otherwise, it returns 0 (zero).

27 Returns 1 if TCL case-sensitivity is in effect for the current process. Otherwise, it returns 0 (zero). (see "casing").

28 Returns 1 if the current Pick/BASIC program is data case-sensitive, or 0, if not. The first time a Pick/BASIC program is entered, the Pick/BASIC case flag is set to the current process' case flag. Any subsequent "casing" statement modifies the Pick/BASIC flag but not the current process' flag. Only the current process' flag is passed between levels. (see "basic" and "compile" commands).

29 Returns 1 if R83-format 'who' is in effect (port.number, account name, user-id) or 0 (zero) if "AP-format" is in effect (port.number, user-id, account name). See the "who" verb for options. (Note that in R83, there was no user-id.)

30 Returns the port.number of the process which has the item locked. (see "locked").

31 Returns the current Spooler form queue number most recently assigned with an "sp-assign".

32 Returns the data frame size for the system.

33 Returns the name of the Pick/BASIC program which called the subroutine.

34 Is currently not supported and should not be used.

35 Returns the total number of physical ports on the system, excluding phantom ports.

36 Returns a non-zero if running a FlashBASIC program, otherwise, it returns a 0 (zero). (AP 6.0 and higher only).

37 Custom Interrupt Handling in Pick/BASIC. A generalized method is provided by which Pick/BASIC applications may handle the break key or any other type of interrupt in a special manner. This function returns the value of an internal location indicating the last interrupt processed and then clears that location. Note that although the only way to poll this value is with the system(37) function in Pick/BASIC, the internal value is ALWAYS set, even if the application is not in Pick/BASIC. The following numbers are valid return codes:

00 No interrupt has occured
03 Another process sent a message to the current line
10 The break key was hit
12 Escape level push
13 Another process TCL'd the current line

Other values are undefined and should not be relied upon.

The system(37) function has only one limitation in that if a process is waiting at input, the user must type a key before the application can poll the interrupt status. All other operations, including sleep, will complete immediately after a break allowing the program to detect that interrupt in real time. This feature has several applications. See the 'Example' section below.

38 Returns the system identification and options. A string with four attributes as follows is returned:

host ^ chip ^ imp ^ opt

host : Underlying host operating system (decimal).
chip : Processor chip code (decimal).
imp : Implementation code (decimal).
opt : Option string (one character per option)

The values of each field are defined in the include "dm,bp,includes sysid.inc" which should be included in programs using this function. Available on AP 6.1 and later.

39 Returns a non-zero (usually 1) if the spelling checker is enabled, or 0 if it is not. (AP releases 5.2.5 and 6.0.0 and higher only).

40 Returns the current tape reel number, or -1 if not attached. (AP releases 6.2.0 and higher only).

41 Returns the Unix Errno variable. (AP releases 6.2.0 and higher only).

100 Returns the system identification:

system;filename:name;release; version;hardware; date

system : The system name, which may contain spaces.
filename : Configuration file name.
name : Contents of the 'name' statement in the configuration file.
release : The current release level.
version : The current version level.
hardware : The type of hardware.
date : The date of the release.

On AP/Unix implementations, the format returned by system(100) is as follows:

AP/Unix: system; o/s name; filename:name; release; version; hardware; boot monitor version; date

system The system name, which may contain spaces.
o /s name "SCO", "AIX", etc.
filename Configuration file name.
name Contents of the 'name' statement in the configuration file.
release Unix system release.
version Unix system version.
hardware Machine hardware name, or serial number.
boot monitor version The release level of the monitor.
date Boot monitor date.
Syntax system(num.expression)
Options
Example
1)  system(37):

When doing an "execute" of a Unix shell command, the Unix command 
will simply abort if it gets a break signal (the normal action in Unix). The 
following code will sense that a break has occured and reexecute the Unix 
instruction, giving the appearance of a standard Pick break-and-continue 
capability:

do.unix:
x = system(37); * Clear the interrupt value
execute "!exec find / -name ap - print"
if system(37) = 10 then goto do.unix; * Break - Return, reexecute

Another useful application is for a Pick/BASIC program to mimic the behavior of 
the Update processor's interrupt handling and redraw the screen background 
if it senses an interrupt. For example:

gosub refresh
open "data"
select
loop
readnext id else exit
read rec from id
name = rec<1>
balance = rec<2>
balance = balance + 50
print @(20,2):name
print @(20,3):balance
if system(37) then gosub refresh; * Screen might be hosed
repeat
stop
refresh:
* Draw the background
print @(-1)
print @(10,1):"Processing Accounts"
print @(10,2):"Name:"
print @(10,3):"Balance:"
return

By using the system(37) in conjunction with the "break off" 
statement, a Pick/BASIC program can implement its own signal handler. For 
example, assume a user wishes to update many items in a file, but he or she 
wants this done atomically, i.e. either all the items in the file must be 
updated or none of the items must be updated. This is a simple form of 
transaction bracketing and can be implemented on previous releases by simply 
turning off the break key. However, this method has the disadvantage of not 
being able to interrupt the process. The system(37) capability provides the 
ability to offer a "controlled" interrupt allowing the user to 
continue, or back out of all changes made so far. This routine could be 
expanded to allow other operations provided it didn't turn the break key 
on (which would cause the system to catch the break and push a level, allowing 
the user to type "end"). The example is as follows:

break off
x = system(37);* clear previous signals
max = 2000
dim xx(max)
for i = 1 to max
readu xx(i) from i
writeu "abc" on i
if system(37) = 10 then gosub interrupt; * break key hit
next i
* Release the locks
for i = 1 to max
release i
next i
stop
interrupt: 
print "Interrupted"
print "Processed ":i:" items"
print "C)ontinue or Q)uit without modifying file:":
in x
print
x = char(x)
if x = "q" then
* Change the items back to the way they were
max = i
for i = 1 to max
* note that write will release the locks along the way
write xx(i) on i
next i
stop
end
return

Finally, system(37) increases the capabilities of Pick in the area of 
interprocess communications. For example, a batch job can poll system(37) 
repeatedly and when it senses an interrupt, it can either simply send a message 
indicating its progress, or do some other, more complex action by reading a 
command item from a file. Note that using the system(37) is much more efficient 
that reading commands and writing status output for every item. An example is 
as follows:

xx = system(37);* clear status
open "data"
for i = 1 to 100000
* In a real program, there should be more work done in the main loop.
* Otherwise, the system(37) becomes comparatively more expensive.
write "abc" on i
if system(37) then execute "msg !0 Processed ":i:" items."
next i
stop

* "z" the preceeding program and then type the following
* tcl (line#) (user) who
*
* The actual command executed is unimportant.  The who command is a
*   good candidate since its cheap and has no side effects.
*
* Note that the msg does NOT work with phantoms, but the "tcl" command
*   will.
*

2)  system(38):
include dm,bp,includes sysid.inc
imp=system(38)
if imp<sys$host>=sys$unix then
* Running on Unix implementation
n=%open( "myfile, O$RDONLY)
....
end

3)  system(100):

crt system(100)
AP/UNIX: RS6000;AIX;pick0:PROD0;2;3;000047311000;6.0.0.M0;27 May 1992
Purpose
Related basic.statements
basic.execute
basic.page
basic.str
basic.%close.apdos
basic.%read.apdos
basic.%write.apdos
basic.matread
basic.onerr
basic.readt
basic.readtl
basic.readv
basic.readtx
basic.readnext
basic.writet
basic.%open.apdos
basic.rewind
basic.weof
tcl.term
tcl.who
basic.casing
basic.execute.unix
active.list
port.number
ue.e070
ue.713c
basic.functions
tcl.config.options
basic.footing
basic.%gethostid
basic.heading
locking.scheme
basic.%putenv
up.input-conversion.fdi
user.exits.introduction
basic.status

tcl.addbi.unix

Command tcl.addbi.unix Verb: Access/Unix
Applicable release versions: AP/Unix
Category Unix (24)
Description extends the functionalities of the Pick Monitor by making new C functions available to Pick/BASIC.

"addbi" adds the user-defined built-in functions defined in the given "function" to the Monitor.

If a list of functions is omitted from the command line, then a list is presumed active. If no list is active, the User Generic Monitor library "libgmu.a" is simply rebuilt to match the list of built-in functions.

Up to 128 user-defined functions can be added to the Monitor.

Built-in functions are defined in the item "user.builtin" in the "dm,messages," file. "addbi" updates this item and creates, in the current directory, the C module "px_user.c" which is compiled and linked with the default Generic Monitor libraries to create a customized Monitor. Added functions can be called directly from BASIC.

User-defined built-in functions may be removed using the "rmbi" command.
Syntax addbi {function {function} ...}
Options
Example
Purpose
Related tcl.set-cmem
basic.cfunc
basic.cfunc.user
basic.%
basic.cfunction
tcl.rmbi
tcl.listbi
tcl.addbi.unix.link

attribute.defining.item.article

Command attribute.defining.item.article Article/Article
Applicable release versions: AP
Category Article (24)
Description Using processing codes in an attribute-defining item.

The Power of Advanced Pick Dictionaries, Part 2:
The Attribute-Defining Item

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

Part 1 of this series described the features available to the Advanced Pick (AP) application programmer through extended processing codes invoked through the d-pointer or file-defining item.

This article will focus on the tools and features available to the application programmer and end user through the use of the AP data dictionary or Attribute-Defining Item.

A different approach to application development:

For the application programmer, writing applications in AP requires a different mind-set than in classic Pick or other Data Bases. Since most of the application functionality can be performed using the dictionaries, the first step in developing an application is to define the file structures. This includes defining inter and intra file relationships.

Once the file structures are defined, the Update processor can be used to build the dictionaries and enter Pick/BASIC subroutines.

After the dictionaries are defined and Pick/BASIC subroutines are written (most subroutines are no more than one screen long), the Update processor can be used to enter and retrieve data.

A different approach to data retrieval:

For the end-user, data retrieval is immediate when using B-tree indicies and the Update processor or Pick/BASIC. Once an index has been created and the index correlative has been defined, the user can access data for that attribute instantaneously.

Consider a name field with an index defined. To access a specific item, the user keys in a partial string and <ctrl>+f to 'cruise' forward in the data base for the person whose name begins with the given string. Another <ctrl>+f will bring up the next person whose name follows alphabetically.

This ability to immediately access data via indexed fields introduces a rather revolutionary concept. That is, item-ids are no longer necessary for data retrieval. You can find the item by 'cruising' through any indexed field - immediately. (There is no limit, other than disk capacity, to the number of indicies that can be created.)

Along those same lines, many printed reports can be replaced by giving users the capability to look-up the information needed. This can be accomplished easily using AP's menu structure and Update processor (with the "look only" option) on indexed dictionaries.

Listed below are some of the application related features AP's processing codes provide:

* on-line edit checking
* item modification using Pick/BASIC program calls
* output formatting using Pick/BASIC program calls
* local and remote indexing capabilities
* limit the number of values for input
* require operator input
* define "view" or display only attributes
* define default attributes to be viewed or updated when "zooming" or jumping from the current file to another predefined file

The following table shows what the processing codes are and from where they can be called.

OUTPUT INPUT
PROCESSING CODE CONVERSION CORRELATIVE CONVERSION
--------------------------------------------------------------
algebraic function x x x
ascending order x
attribute index correlative x
call BASIC subroutine x x x
character update x
concatenate x x
date conversion x x x
display only x
f-math correlative x x x
group extract x x x
length code x x x
mask character x x x
mask hexadecimal x x x
mask left & right justify x x x
mask time x x x
must input x
pattern match x x x
range x x x
remote index correlative x
substitution x x x
text extraction x x x
translate x x x
user exit x x
value code x
za x x
zip code x x x

In addition to the new processing codes, all of the existing R83 conversions and correlatives are available in Advanced Pick.

The rules for using processing codes:

A key to writing applications in AP, is knowing where to put the processing codes in the Attribute-Defining Item. In general, the following rules apply:

* Processing codes on output-conversion manipulate data immediately before output.
* Processing codes on correlative are used to preprocess data.
* Processing codes on input-conversion are applied immediately after entry of data.

The Attribute-Defining Item has four new dictionary attributes in AP. They are input-conversion, macro, output-macro, and description.

Note: In AP releases on or after April 25, 1991, there are an additional 11 dictionary attributes added to both the File and Attribute-Defining Items. These "hotkeys" are used to call Pick/BASIC subroutines from the Update processor. More on these later.

A new look to Attribute-Defining Items:

Let's create an Attribute-Defining Item for the orders file called customer. With this attribute, we will translate to the customer file for the name on output, utilize a remote index to look up valid customers (and optionally enter or update customer items), require input on this attribute, and limit the number of values allowed on this attribute to one. We will do all this without a single line of Pick/BASIC code. To view/edit the Attribute-Defining Item, the Pick/BASIC program "ud" is used:

ud orders customer
DICT orders 'customer'
NAME DATA DESCRIPTION
dictionary-code a Valid codes are a or s.
attribute-count 1 Position of data.
substitute-header customer.name User/programmer defined.
structure dependent structure.
output-conversion tcustomer.file;x;;1 Translate name on output
correlative
attribute-type l Valid types are:
l,r,t,u,w,ww,lx,rx,tx
column-width 10 Width for output.
input-conversion i Local index on
orders(customer)
icustomer;a1 Remote index on
customer(name)
mi Defines must input field.
v1 Only one value allowed.
macro name address zip Default attributes
output-macro Not used.
description Enter customer name On-line UP help messages.

That was easy!

Now, we'll create another attribute in the orders file called part#. This attribute will control another attribute in a controlling/dependent structure. It will also translate the description of the part from the parts file, call a Pick/BASIC program to display the quantity on hand, require input and translate to the parts file for valid entry. If this is a new part#, the ability to "zoom" to the parts file and enter a new part number is provided.

ud orders part#
DICT orders 'part#'
NAME DATA DESCRIPTION
dictionary-code a Valid codes are a or s.
attribute-count 2 Position of data.
substitute-header part.number User/programmer defined.
structure c;3 Controls attribute 3.
output-conversion tparts;x;;1 Translate
correlative call display.qoh Program to filter info
attribute-type l Valid types are l,r,t,u,w,ww,x.
column-width 25 Width for output.
input-conversion iparts;a0 Remote index
mi Must input field.
macro part# qoh price Default attributes
output-macro Not used.
description Enter part number. On-line UP help messages.

A faster application prototype:

After the orders file and the two dictionary items (customer and part#) have been created, the Update processor can be used to enter data into the file. The UP command to generate an operable data entry screen would be u orders customer part# . This screen would look like:

orders NEW ITEM
orders _________
customer _________
part# _________

When entering data into the orders file, the customer and part# attributes have all the abilities and restrictions that were designed into them.

The next example will show the 'hotkey' feature. That is the ability to call a Pick/BASIC subroutine from any attribute from the Update processor. Remember that a subroutine called from output conversion, correlative or input-conversion will be automatically executed at the default time by a carriage return.

To call a Pick/BASIC subroutine while in the Update processor on a particular attribute, type control x<0-9>. Typing control x<1>, for example will execute the subroutine called by hotkey1. Typing control x<2> will execute the subroutine called by hotkey2, etc... If no subroutine is called from that particular attribute, then the system looks at the file pointer for any defined calls. If any are present, they will be executed. Any subroutine calls on hotkey.all will also be executed by control x<0-9>.

ud orders state
DICT orders 'state'
NAME DATA DESCRIPTION
dictionary-code a
attribute-count 5
substitute-header
structure
output-conversion tstates;x;;0
correlative
attribute-type l
column-width 20
input-conversion istates;0
macro city state
output-macro
description
hotkey.all sub called by control x<0-9>
hotkey1 call list.states sub called by control x<1>
hotkey2 sub called by control x<2>
hotkey3 sub called by control x<3>
hotkey4 sub called by control x<4>
hotkey5 sub called by control x<5>
hotkey6 sub called by control x<6>
hotkey7 sub called by control x<7>
hotkey8 sub called by control x<8>
hotkey9 sub called by control x<9>
hotkey0 sub called by control x<0>

By modifying our UP command to add the state attribute, we have the following screen

u orders customer part# state
orders NEW ITEM
orders __________
customer _________
part# __________
state __________

In the example above, when the user types control x<1> at the state attribute, the subroutine list.states will execute. Control will then return to the Update processor.

Pick/BASIC program 'list.states'

subroutine list.states(value)
execute 'sort states city state'
return

To summarize, AP provides many features for both the application programmer and the end user through the use of dictionaries. When these features are used in conjunction with the Update processor, the possibilities are only limited to your imagination.
Syntax
Options
Example
Purpose
Related

tcl.@

Command tcl.@ Definition/TCL
Applicable release versions: AP 6.2
Category TCL (746)
Description indicates a Pick shell variable.

A Pick shell variable.name may contain any combination of alphabetic and numeric characters. The period and underscore characters are also valid.

Shell variables are pushed up and down all execute levels and persist until logoff. They are essentially the TCL analog of BASIC named common variables.

A Pick shell variable can be modified with the TCL command "set variable.name{=value}", and cleared with the command "unset variable.name". The current list of user variables can be displayed with the "penv" verb. The following user variables are examined by the system. Note that variables begining with the word "sys" are reserved for future system usage. The "$" character is optional, but is recommended for usage on all modifiable variables.

@$MESSAGES The contents of this variable are used to locate the system error messages. The format of this variable is the full path name of the desired alternate messages file. To allow the use of an alternate messages file, insert a line similar to the following, "set messages=dm,msg.file.name," as the very first line of the user macro. All subsequent error messages will use this alternate file until the user logs off the file.

@$PATH The contents of this variable are used to direct the system to default accounts for verbs, BASIC main programs, BASIC subroutines, and files. When the system fails to find one of these objects within the current master dictionary, it successively searches each of the account master dictionaries in this list. The list is of the following format: "account.name1,account.name2,account.name3...". Up to 8 account names may be listed. Note that there must NOT be a comma at the end of the list. When doing a "set" of this variable, the system pre-checks each of the account names. If an error is found, then the text of the list will be terminated with the "(ERR!)" string.

@$PROMPT The contents of this variable dictate the appearance of the TCL prompt. The system expects this variable to have the following format: "prefix,prompt1,prompt2". The "prefix" parameter is a textual indicator which is displayed before the prompt. The "prompt1" parameter is the prompt character to be used normally at TCL. The "prompt2" parameter is the prompt character to be used when a select list is active.

@$SYS.COMPILER The contents of this variable dictate the compatibility setting of the BASIC compiler. See the "$options" token for the BASIC compiler for more information about this.

Several variables have values which are dynamically computed at run-time. The currently supported list includes the following:

@AM Attribute Mark
@FM Attribute Mark (for licensee compatibility)
@VM Value Mark
@SVM SubValue Mark
@SM SubValue Mark (for licensee compatibility)
@USER User name
@WHO User name (for licensee compatibility)
@ACCOUNT Account
@LOGNAME Account (for licensee compatibility)
@PIB User Pib
@USERNO PIB (for licensee compatibility)
@TIME Current System Time
@DATE Current System Date
@DAY Current System Day of Month
@MONTH Current System Month of Year
@YEAR Current System 2-digit Year
@ID Same as "*A0" (for licencee compatibility)
@SYSTEM.RETURN.CODE Returns number of items processed by the most recent access statement.

If a shell variable occurs directly next to other text, the identifier (starting after the "@", but before the "$" if present) may be surrounded by the "{" and "}" characters.

The second version of the @ syntax executes the specified TCL command and replaces the @`...` sequence with the output of that command.

Substitution of TCL shell variables is active for all TCL commands including those issued from macros, paragraphs, interactive commands, and BASIC executes. Transitive expansions (those expansions whose values contain other variable definitions) are allowed except where noted below.

At TCL, several rules are in effect to prevent shell variables from interfering with previously existing code. If the "@" character appears within single quotes, then the corresponding variable is NOT expanded. Also, the sequence "@@" is expanded into "@". Finally, any shell variable identifiers which are not found in the current list are NOT expanded at TCL.

TCL shell variables are passed up and down between levels so they may be used freely across BASIC execute boundaries.

All shell variables are released and cleared when logging off of the system.

The conversion processor expands conversion values beginning with the "@" character to their respective values. Note that transitive expansions are not allowed in this case for performance reasons.

The menu processor expands all menu definitions based on the above mentioned rules for TCL.

Shell variables may be referenced and assigned within a BASIC program. Note that the TCL shell capability is not available from BASIC. Also, shell variables cannot be assigned directly by a complex BASIC statement (like "locate" for instance). They must be assigned with simple assignement statement.
Syntax @{$}variable.name}
@`TCL.Command`
Options
Example
The following sequence of commands shows some typical interraction from TCL:

:set prompt=PROD,>,?
PROD>set myfile="dm,bp,"
PROD>who
70 john ba
PROD>penv
prompt=PROD,>,?
myfile=dm,bp,
PROD>select @$myfile sampling 5

[4042] 5 items selected out of 5 sampling items
PROD?list @$myfile heading "Report from @logname"
Report from ba
dm,bp,........

color
pick
set-imap
shp-kill
restore-accounts

[405] 5 items listed out of 5 items
PROD>display @system.return.code
5
PROD>display @who|@{time}xxx|@date
john|15:27:12xxx|17 May 1994
PROD>unset prompt
:env
myfile=dm,bp,

Shell variables can also be accessed from conversions.  Assume that a file 
called junk has the following attribute-defining item:
DICT junk 'myattr' size = 45
dictionary-code   a
attribute-count   1
substitute-header
structure
output-conversion @$mycv
correlative
attribute-type    L
column-width      10
.....

Assume that the file contains one item called "itm1" which contains 
the text "abc123". Notice how the conversion can be modified without 
changing the attribute definition:
set mycv=mcu
list junk xx
Page   1    junk

junk...... xx.........

1          ABC123

[405] 1 items listed out of 1 items.
set mycv=mca
list junk xx
Page   1    junk

junk...... xx.........

1          abc

[405] 1 items listed out of 1 items.

Multi-lingual systems are facilitated by use of the "@$messages" 
variable. Assume that a system exists with 30 English speaking users, and 20 
French speaking users. Assume that the standard English messages are stored in 
"dm,messages" (which is the default), and that the French ones are in 
"dm,msg.French,". By default, all users get their messages from 
"dm,messages,". To cause French speaking users to use French error 
messages, it is a simple matter of inserting the following line as the first 
thing in each French users' user macro:

set messages="dm,messages,"
Purpose
Related tcl.penv
tcl.set
tcl.unset
ue.91
tcl.tcl-prompt
tcl.field
tcl.background
basic.$options

basic.debugger.b

Command basic.debugger.b Command/BASIC: Debugger
Applicable release versions: AP, R83, AP 6.0 FlashBASIC
Category BASIC: Debugger (38)
Description establishes a "breakpoint" condition in the break point table, which causes the program to enter the FlashBASIC or Pick/BASIC the debugger when the condition defined in the breakpoint expression is met.

The valid comparative operators are >,<, and =.

A "+" (plus) character is displayed for each breakpoint successfully entered into the table until the table is full. In FlashBASIC, there is no limit to the number of table entries.

Note that the spaces between the arguments in the syntax are there for readability; they are NOT allowed when composing breakpoints.

Once a breakpoint is placed in the table, the debugger is entered each time the breakpoint is met.

Note that the syntax form, "bvariable", is only supported in Advanced Pick releases with FlashBASIC. It breaks into the debugger each time the specified variable changes.
Syntax {Flash.routine.name:}b
{Flash.routine.name:}b variable operator variable
{Flash.routine.name:}b variable operator numeric.literal
{Flash.routine.name:}b variable operator "literal.string"
{Flash.routine.name:}b variable
{Flash.routine.name:}b $operator line.number
Options
Example
run bp fred (d
*E1
*b$=5

This sets a break point on line 5.  The break point remains until execution is 
complete, or it is manually removed.

*sally:b

When running FlashBASIC, this command will set a breakpoint that will cause 
execution to pause every time the subroutine "sally" is entered.
Purpose
Related system.debugger.k
basic.debugger.d
basic.debugger.k
basic.debug
basic.debugger.overview
basic.debugger.n
basic.debugger.t
basic.debugger.variable.references

basic.debugger.c

Command basic.debugger.c Command/BASIC: Debugger
Applicable release versions: AP, AP 6.0 FlashBASIC
Category BASIC: Debugger (38)
Description toggles on or off the display of the current source line when stepping through the program with <ctrl>+j. When this function is on, the line is displayed AFTER it has been executed.

The "c!" form of the command is only available with FlashBASIC. It is identical to the "c" command, except that it displays the source line BEFORE it has been executed. (AP 6.0 FlashBASIC only).
Syntax c
Options
Example
Purpose
Related basic.debugger.l
basic.debugger.g
basic.debugger.overview
basic.debugger.e
basic.debugger.z
flash.basic
<ctrl>j

flash.basic.notes

Command flash.basic.notes Article/Article
Applicable release versions: AP 6.0 FlashBASIC
Category Article (24)
Description Unix File Space

When running, FlashBASIC programs do not require Unix file space. However, the C compiler requires about 2 Megs of space in the current Unix directory (This is usually the root directory) and about 5-10 Megs in the /tmp directory. This amount varies depending upon the size of the module(s) being compiled, the number of module's being compiled (The default behavior only allows one compile at any one time), and the platform (The RS6000 uses quite a bit more than the other platforms). Additionally, the current Unix directory from which the "ap" application is run must have write permission. Note that these requirements are probably already met on existing systems.

Pick File Space

FlashBASIC object code is appended to the standard Pick/BASIC object. Assuming one uses the default optimization, the combined size of the two objects will be about 4-5 times that of the original (The SCO version uses slightly less). The Pick file space must be available for this extra object. The amount of object space taken by programs can be found by using the "istat" utility with the "(r" option on the "dict" of each Pick/BASIC program file.

Pick Overflow

An advantage of FlashBASIC is that it uses very little Pick overflow (only 1-2 frames for each module regardless of its size). Therefore, it is not necessary to keep a huge amount of overflow available for applications to use as workspace.

Unix Swap Space

Instead of Pick overflow, FlashBASIC uses Unix swap space making it coexist more easily with other Unix applications. Additionally, FlashBASIC loads all of its object code into swap space as well. Swap space must always be sufficient as the machine crashes brutally when it runs out. Remember that Unix swap space uses disk space that must be taken from either Pick or Unix file space or unallocated disk space. At minimum, the amount of swap space should be at least twice the amount of real memory on an RS6000 and equal to real memory on other platforms. For most systems, this minimum will be too low and a more complicated formula must be used which is as follows:

- Start with 8 megs of swap for the kernel and system processes.

- If other Unix applications are being used on the system, then add their swap space requirements. Obtain this information from the documentation that accompanied those applications or contact the manufacturer.

- Find the size of all standard Pick objects by using the "istat" command with the "(rs" options on every dict of every file containing Pick/BASIC object. The size of the object code will be the "pointer item byte count" field in the record produced by "istat". Add up this byte count for all object files. Multiply this number by four to get the estimated size of the FlashBASIC object and add this number to the total.

- Determine the amount of overflow that the current Pick application uses when completely active. This can be done by noting the amount of overflow available when the machine boots, starting all active users, and noting the amount of overflow available when all users are active. Compute this difference and multiply by the frame size to get the number of bytes. Experimentation has indicated that a small application will require about 100K of overflow work space per user, and medium to large applications require about 500K per user. Multiply this estimate by 1.2 to get a rough estimate of the swap space the FlashBASIC code will need at run time. Add this figure to the total.

- Add 3-5 megabytes for FlashBASIC compiles. If the user wishes to allow more than one concurrent FlashBASIC compilation, then he/she must add 3-5 megabytes for each user that may compile on the system.

- Add a few extra megabytes for safety.

On an RS6000 or DG, extra swap may be added while Unix is running. SCO users must completely reinstall Unix to change the swap space.

Hardware Requirements

The SCO version requires a floating point coprocessor to run. Attempts to run FlashBASIC on a SCO system without a coprocessor will succeed but performance will be slower than standard Pick/BASIC.

Pick Configuration Settings

The "pick0" file is a Unix file in the directory "/usr/lib/pick/" which determines configuration settings for the "ap" application. To edit it, use a Unix editor like "vi". See the Advanced Pick Installation Manual for more information.

A new parameter has been added to the "pick0" file called "basic". This parameter must be equal to or greater than the size of all FlashBASIC objects that are expected to be active at one time. Remember that this size is computed by multiplying current Pick/BASIC object size by 4. Failure to set this parameter sufficiently high can result in extremely poor performance and a large increase in required Unix swap space.

The "core" parameter in the "pick0" file should be reduced when running primarily FlashBASIC applications on a system. To determine a good size, leave this parameter the way it is on Pick 5.2, boot the system, bring up all users in Flash, and run the buffers with the (sl options. Note the "Referenced" number (not the percentage, but the larger number before it), multiply it times the frame size, and divide by 1024 to get a good estimate of the core size required for reasonable performance. Then shutdown the Pick machine, reset the parameter, and reboot.

Real Memory Requirements

Real memory requirements for a given system are generally a function of active Pick/BASIC object size plus work space requirements. FlashBASIC produces much larger objects (4 times the size), but uses only slightly more work space. Thus, a system which uses memory primarily for workspace should run FlashBASIC with the same amount of memory or only slightly more. Systems which use primarily workspace memory are those systems currently running a large number of users (say 50 or more) with standard Pick/BASIC. Even systems with a large amount of object code should not require more real memory, as only a small amount of this object code needs to be available in real memory during normal operations.

For example, a small application (about 250K of Pick/BASIC object) was found to run 60 users in standard Pick/BASIC with 16 Megs of real memory. When FlashBASIC was run on the same configuration, the program sped up by a factor of two despite slightly higher paging activity. Thus performance was adequate with the same amount of memory because the amount of memory the object required was insignificant compared to the workspace requirements for so many users.

A much larger application with about 60 Megabytes of Pick/BASIC was converted to FlashBASIC object with a total size of about 260 Megabytes. Although it would appear that such a large increase in object size would necessitate an increase in real memory useage as well, this was not the case. It turned out that less than 5 Megabytes of the final, FlashBASIC object code was being actively used. This was found by bringing the application to an active state using Flash, and running the "shpstat" utility which displays the amount of memory used by all active FlashBASIC applications on the system.

Note that with any sized application, FlashBASIC will respond much more favorably to extra memory than standard Pick/BASIC. For example, when the small application mentioned above was given another 16 Megs of real memory, standard Pick/BASIC remained at the same performance level, but FlashBASIC nearly doubled its speed.

In summary, the customer should experiment with his/her specific application, but experimentation has indicated that most applications will not require more memory to run FlashBASIC than they do in the current Pick/BASIC.

Terminal Definitions

FlashBASIC will run with standard Pick terminal definitions. However, a speed increase of up to 200% can be realized on screen i/o by creating optimized terminal definitions. To do this, logto dm, and type "term xxx (co" where xxx is the device name. Note that this optimization is not available for printer devices or devices which use user-defined functions.

Shipping Procedures

No FlashBASIC object code will be shipped with the standard release. All FlashBASIC objects and/or optimized terminal definitions must be created by the customer.

Compile Time

Because of the extra optimization FlashBASIC does, its compile time is significantly longer than standard Pick/BASIC (about 4-10 times as long). Memory requirements during compilation are also much higher. Because of this, it is recommended that customers compile only when the machine is inactive. This is particularly critical on the RS6000.

Using FlashBASIC without source

The FlashBASIC compiler does not require source. To compile without source, use the "w" option when compiling. See Advanced Pick Reference Manual for more information.

Known Incompatibilities

Mixing FlashBASIC and Interpreted Code:

If a mainline program is compiled with the FlashBASIC compiler, all its subroutines must also have been produced with the FlashBASIC compiler. (see "compile").

No such limitation is present on programs that "execute" other programs. However, named commons will not be shared between FlashBASIC programs and standard Pick/BASIC programs.

Access:

FlashBASIC code is only run when called from a dictionary definition on releases 6.1.0 and above.

The "chain" statement:

The Pick/BASIC "chain" may be used freely to transfer control to other programs, but variables will NOT be restored if a "run" with the "i" option is attempted later. This restriction holds if a FlashBASIC application is involved with the "chain" in any way.

"%" (Percent) calls:

FlashBASIC currently supports calling C routines, but NOT assembly routines with the percent call. (see the various functions in Pick/BASIC that begin with "%"). Additionly, FlashBASIC cannot pass arrays to % functions.

BASIC subroutines:

FlashBASIC code allows a maximum of 62 parameters on a call. This limitation does not include commons which have no limit.

The Pick/BASIC Debugger:

The FlashBASIC debugger does not support logical conditions on breaks.

The FlashBASIC debugger does not allow any arguments on the "g" command.

The FlashBASIC debugger does not actually do anything when it prints "object verifies" on the "$" command.

The FlashBASIC debugger does not allow continuing after an abort.

The practice of patching variables in the debugger after a warning message does not work.

The FlashBASIC debugger contains several enhancements. Use the "help" command in the debugger to view them.

Arithmetic:

String math is not supported by FlashBASIC.

When using the (f option FlashBASIC uses the host machine's floating point arithmetic, which provides faster and more accurate results. However, if a module is compiled without the (f option, FlashBASIC will truncate addition, subtraction, multiplication, division, and remainder (modulo) in the same manner as R83 and standard Pick/BASIC. Modules compiled with and without the (f switch may be mixed freely in an application.

The maximum size of a number in FlashBASIC is the same as in R83, and AP when not using string math. This maximum number is {+/-} 140737488355327*(10 ^ (-p)) where p is the current precision.

With the (f switch, FlashBASIC will accept and compute numbers exceeding this maximum, maintaining an accuracy of 14 significant digits.

Arrays:

Array bounds checking is absent in FlashBASIC by default to provide greater speed. If this causes problems due to lack of reliability in the application, the user may enable array bounds checking on desired modules with the compile-time "b" switch. Modules compiled with and without the (b switch may be mixed freely in an application.
Syntax
Options
Example
Purpose
Related pointer.item

cfunc.readv

Command cfunc.readv C Function/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description equivalent to the Pick/BASIC statement: readv

Depending upon type, _CP_read acts as the following Pick/BASIC commands:

type Pick/BASIC statement

_CP_READV readv result from expression1, string, expression2

_CP_READVU readvu result from expression1, string, expression2

_CP_READVUL readvu result from expression, string, expression2

The value parameter returns a 1 if the item is locked.

If value is not needed, the user may pass (int*) 0.

The _CP_readv call uses the same optimized read routine as FlashBASIC which, from the 6.1 release onwards, is about 2-5 times faster than that which is used by Access and standard Pick/BASIC.

The expression1 should be an integer file descriptor returned by the _CP_open call.

This function returns -1 if an error occurs. The error code is contained in _CP_errno. If the attribute number is bad, then _CP_errno will contain PE_BADATTR.
Syntax int _CP_readv(int type, CPSTR** result, int expression1, CPSTR* string, int expression2, int* value)
Options
Example
/* The following example reads the first attribute of the item "myid" 
from "myfile". */

CPSTR * s = _CP_mkstr("myfile");
CPSTR * id = _CP_mkstr("myid");
CPSTR * xx = _CP_str_null;
int f;

_CP_open(&f,_CP_str_null,s);
_CP_readv(_CP_READV, xx, f, id, 1, 0);
Purpose
Related cfunc.introduction
cfunc.writev

data.management

Command data.management Introductory/Access: Modifiers
Applicable release versions:
Category Access: Modifiers (8)
Description overview of the design philosophy behind Pick

Pick is specifically designed for data management. All data in Pick is stored in items within files. Items within these files are divided into sets called attributes which contain one, multiple, or no values.

Subsetting the Pick model into the tabulating model (punch cards, batch processing); items would be called records, attributes would be called fields, and item-ids would be called record keys. Items, attributes, and values can be of variable length. Items and attributes can contain multiple values or sets of values and are separated by specific delimiters. Items are delimited by segment marks (hex FF). Attributes are delimited by attribute marks (hex FE). Multiple values are delimited by value marks (hex FD).
Because delimiters are used, the length of values within attributes doesn't have to be more than the actual physical length of the data. This gives Pick a distinct advantage over traditional systems in that items are of variable rather than fixed length. This not only improves efficiency since disk access time is reduced because of the smaller items, but the amount of disk space required to support the data base is substantially reduced.

Traditional
EDP Terminology Pick Terminology

Disk Physical Level
Partition Partition
Cluster Frame
Block Block
File System
Directory Dictionary
File File
Record (Primary key) Item (Item-id)
Field (Alternate key) Attribute (Index-key)
Values Values

Items that are stored in a file may be accessed in several ways, including:
Directly, using the item-id as the key,
Sequentially in the hashing sequence,
Sequentially in a sorted sequence,
By index key.

The direct file access technique, using the item-id to locate the item within the file, is an efficient method of locating data and lends itself to the on-line nature of the Pick System. The system overhead required to access an item using direct file access is independent of the actual file size. Items may also be indexed by attributes and accessed by index key.

Pick dictionary defining items allow both simple and complex conversions and correlatives to be defined using the a-type processing code, among others. The instructions for the formation of index keys are specified using these same a-processing codes. As many indexes as necessary may be created for a file. The root fid (frame id) and a processing code for each index are stored as a single value in attribute 8 (correlative) of the file-defining item.

Indexes are created by the TCL verb, create-index, and stored on the disk in ASCII sequence within a B-tree (balanced-tree) structure. Whenever the file is changed, the indexes, if affected, are also changed automatically by the system.

For example, if an item is deleted, all index entries that point to that item are also deleted and changed to point to the next item. Indexes can be used in Pick/BASIC programs through the key and root statements. Indexes are also used by verbs such as list, sselect, and sort, if there is an index corresponding to the sort keys.

Files can be updated through the bridge correlative processing codes, by Pick/BASIC programs, and through the Update processor (UP).

Files are stored on disk in blocks called frames. The frames are uniform in size (1024 or 2048 bytes). The primary file space physically consists of a contiguous set of disk frames. The beginning frame is the base frame and the number of contiguous frames or groups (including the base frame) is the modulo of the file. The modulo is defined at the time the file is created or resized. The system automatically adds or removes frames to or from groups as the amount of data (number and/or size of items) within the group expands or contracts. The frames added automatically by the system are added to what is called the secondary file space. This means you do not need to redimension a file as the amount of data in that file increases or decreases.

Consider this example file which was initially allocated seven contigious frames (modulo 7) in Primary Space. As items were added to the file, they were allocated to groups through the hashing algorithm. Some groups required additional frames. These frames were allocated from Secondary File Space. Frames within a group were explicitly linked together.

Primary Secondary
File Space File Space
---------- -----------------------------------

Group 1 ------- --------
| |--------| |
------- --------
Group 2 -------
| |
-------
Group 3 ------- -------- ------- -------
| |--------| |-------| |-------| |
------- -------- ------- -------
Group 4 -------
| |
-------
Group 5 ------- --------
| |--------| |
------- --------
Group 6 -------
| |
-------
Group 7 ------- --------
| |--------| |
------- --------

Items are distributed to the various groups within a file based on a hashing algorithm that calculates the frame identification number (fid) of the first frame in the group. Items are distributed quasi-randomly between groups and sequentially within a group. This quasi-randomness is achieved by using the item-id directly in the hashing algorithm. Because of the nature of the mathematical relationship defining the hashing algorithm, modulo numbers that are multiples of 2 or 5 should not be assigned.

To enable data transfer to and from disk to occur at optimum efficiency, remember to set the modulo of the file to the nearest prime number above that required to set the number of frames per group below unity (50 to 75 percent utilization traded for single disk access speed, etc.) based on the amount of data storage anticipated. This feature makes the system more efficient in that the probability of two or more users accessing the same group at the same time is reduced because of the algorithm of data distribution between groups.

Number-of-Items X Average-size-of-Items (Bytes) / Frame-Size (Bytes)

The result should be increased to the next largest prime number.

The frame size for a particular version of Advanced Pick can be determined by executing the "what" TCL command. The number of available bytes within a frame is listed on the first line of the report under "dfsize". The actual frame size is determined by rounding the "dfsize" up to the next power of 2. The difference between "dfsize" and actual frame size is used to hold the frame linkages (forward and backward pointers).

When more than 50 percent of the groups have more than one frame, or the utilization gets below 50 percent, reallocate the files.
One brute-force method of resizing the file is:

1. Creating a new file with the desired modulo.
2. Copying all items from the old file into the new file.
3. Deleting the old file.
4. Renaming the new file to the old file name.

When resizing in this manner, you must explicitly copy the index and other data from the old file's file-defining item to the new file's file-defining item before renaming all index and subroutine calls from the old file.

Files may also be reallocated using the system’s save and restore commands. When the save and restore commands are used, the indexes are handled automatically. Prior to saving the system on magnetic media, attribute 13 of the file dictionary file-defining item may be set to the new modulo for that file. When the system is restored, all files will be reallocated according to the new modulo specified in attribute 13. When attribute 13 is not specified, the file is restored exactly as it was saved. The save and restore process allows reallocation of many files at one time.

Note that items within files are saved to tape in group sequence. Because restoring to a new modulo redistributes items within the file space, the number of disk reads is considerably increased during a restore to a new modulo, slowing this process noticeably. F-resize is a program provided with the system to automatically calculate new modulos and mark attribute 13 of the files appropriately using the current statistics in the file-of-files as modified by the last file-save.

Specific TCL verbs (system-level commands) exist to manage files as listed below. Refer to the section "Terminal Control Language" for an overview of the terminal control language. Refer to the separate entries for each verb in the body of the Advanced Pick Reference Manual for more detailed information.

clear-file create-file rename-file
copy delete-file steal-file

Dictionaries

Dictionary items are used by the Pick System to describe, define, locate, and, in general, operate on data within the files to which they point. Many operations are preprogrammed functions that process the data in associated files at the system level instead of at the program level, enhancing overall system performance. Some of these operations include the definition of relationships between and within files.

Relationships between files are expressed using bridge, index, or translate processing codes. Features such as these processing codes provide the ability to cruise and zoom through the data base. Refer to the section "Update processor" for more information about cruising, zooming, and using UP.

Relationships within files are expressed through the structure controlling attribute (attribute 4) of an attribute-defining item.
Each data file in the system has one dictionary. A dictionary may have several files associated with it. Dictionaries associated with data files contain items such as attribute-defining items, file-defining items (for the associated data files) and synonym-defining items (additional views of attributes after different processing), as well as compiled Pick/BASIC programs.
Attribute 1, the dictionary code attribute (referred to as the d/code) identifies the item type. If the attribute contains an "a", it is an attribute-defining item. If the attribute contains a "d", it is a file-defining item. If the attribute contains a "q", it is a synonym-defining item.

There are three types of dictionaries: system, master, and file.

System Dictionary - There is only one system dictionary per system. Items within the system dictionary (mds) point to account master dictionaries. The "mds" file can only be accessed on the dm account.

Master Dictionary - There is one master dictionary (md) for each account. When a new account is created, a standard set of vocabulary items are copied into the new account's md. Items within Master Dictionaries point to file dictionaries.

File Dictionaries - There are multiple, distributed file dictionaries among various accounts. Items within file dictionaries point to data files. File-defining items, synonym-defining items and attribute-defining items are also present in file dictionaries. Pointers to compiled Pick/BASIC programs are only present in file dictionaries.

Dictionaries as Operators

The Pick dictionary is a file consisting of items that contain 18 attributes. Each dictionary item can be considered as a vector operator of 18 elements, some of which contain operations to be performed on the specified attribute in the associated file. One element identifies the attribute within the associated file that is the operand.

File-defining items operate specifically on attribute 0 of the associated file. File-defining items also contain system information specific to the associated file. Attribute-defining items may operate on any other attribute within the associated data file or dictionary.

Functions (or programs) defined at the system level (or by the user) can be assigned to the appropriate attributes of the attribute-defining item allowing an operation to be defined in minutes at the system level. In many cases the generation of complex programs in a high level language can be avoided, and this vector provides a shorthand language for generating programs.

Data can be entered through UP or a Pick/BASIC program which passes data through the specified attribute-defining item within the data file dictionary for modification and stores the data in the specified attribute of the data file. When the data is viewed using UP or retrieved using Access or Pick/BASIC, it passes from the attribute in the data file through the data file dictionary for modification prior to output. Secondary files may be involved if the operation specified in the dictionary item is a translation.

Pick Dictionary Structure:

System Dictionary (mds, one per system)
|
+----------------------+
| |
----------------- -----------------
Master Dictionary Master Dictionary (one per account)
|
+---------------------+
| |
----------------- -----------------
File Dictionary File Dictionary (one per file)
| |
----------------- -----------------
Data File Data File
|
-----------------
Data File

Master Dictionary

There is one master dictionary (md) file for each account. When a new account is created, a standard set of vocabulary items are copied into the new account's master dictionary. The following types of items are contained in master dictionaries:

Attribute-defining items
File-defining items
Synonym-defining items
Macros
Menus
Verbs
Connectives
Cataloged Pick/BASIC program pointers
PROCs

File-defining items (d-pointers) and synonym-defining items (q-pointers) are two types of file pointers found in an md. File-defining items point to files within the current account. Synonym-defining items can point to files either within the current account or within other accounts.

There is generally only one file-defining item within a dictionary. Attributes 2 and 3 of file-defining items in an account md contain the base fid and modulo respectively of the file dictionary to which the item points. If the dictionary references more than one data file, attributes 2 and 3 contain base fid and modulo data respectively for the associated data file. The usage and definition of the attributes in the master dictionary file-defining item are:

Attribute 0 (Item-id) Name of the file being defined.
Attribute 1 Dictionary Code d and other options.
Attribute 2 Base frame number of the associated file.
Attribute 3 Number of contiguous frames in the primary file space of the file.
Attribute 4 Reserved and unavailable
Attribute 5 Retrieval locks
Attribute 6 Contains update locks
Attribute 7 Password required to access the md
Attribute 8 Reserved and unavailable
Attribute 9 Attribute "type" or justification
Attribute 10 Number of character spaces to be allocated for displaying the data within the attribute on Access reports
Attribute 11 Reserved and unavailable
Attribute 12 Reserved and unavailable
Attribute 13 Reallocation, used in the save and restore process to redefine the value of the modulo of the associated file.
Attribute 17 Description of the file

To change the information in the "mds" file, use the Update processor. Items can be added, deleted, or modified by executing one of the following command sequences from the dm account:

u mds account.name
create-account account.name
account-maint account.name

UP displays the contents of attributes 1 through 10 (with default values in place for new accounts). To add to the contents of attribute 13, move the cursor to the end of attribute 10, press <return> three times and add the new modulo surrounded by parentheses to resize the master dictionary in attribute 13.

Attribute-Defining Items

Attribute-defining items (ADIs) define views of attributes and processing to be applied to them when used in Update, Access, and BASIC. For a complete explanation, see the entry "attribute-defining items".

File-Defining Items

File-defining items (fdi) define files, default views of them, indexes to be maintained for the files, audit trail information, as well as some of the processing that automatically takes place when items in files are updated. For a complete explanation, see the entry "file-defining items".

Synonym-Defining Items

Synonym-defining items, also known as q-pointers, are used in account master dictionaries to point to other files. The files may be dictionaries or data files within the current or in other accounts. In general, only the first four attributes are used (attributes 0, 1, 2, and 3). For a complete explanation, see the entry "synonym-defining items".

System Security

The Pick System maintains several levels and forms of security. There are user and master dictionary passwords, system privilege levels, file retrieval and update lock codes, and restricted access to the system level. For a complete explanation, see the entry "security".
Syntax
Options
Example
Purpose
Related

flash.basic.differences

Command flash.basic.differences Definition/BASIC Program
Applicable release versions: AP 6.0 FlashBASIC
Category BASIC Program (486)
Description describes the differences between Pick/BASIC and FlashBASIC.

Platforms Supported

FlashBASIC is supported on the AIX, the DG/UX, and the SCO Unix implementations on releases of 6.0 and higher.

Mixing FlashBASIC and Interpreted Code:

If a mainline program is compiled with the "o" option, all its subroutines must also have been produced with the FlashBASIC compiler. (see "compile").

Access:

FlashBASIC code is never run when called directly from a dictionary definition.

The "chain" statement:

The Pick/BASIC "chain" may be used freely to transfer control to other programs, but variables will NOT be restored if a "run" with the "i" option is attempted later. This restriction holds if a FlashBASIC application is involved with the "chain" in any way.

"%" (Percent) calls:

FlashBASIC currently supports calling C routines, but NOT assembly routines with the percent call. (see the various functions in Pick/BASIC that begin with "%").

FlashBASIC code allows a maximum of 62 parameters on an external subroutine call.

The "rnd" function:

The Pick/BASIC Debugger:

The FlashBASIC debugger does not support logical conditions on breaks.

The FlashBASIC debugger does not allow any arguments on the "g" command.

The FlashBASIC debugger does not actually do anything when it prints "object verifies" on the "$" command.

The FlashBASIC debugger does not allow continuing after an abort.

The practice of patching variables in the debugger after a warning message does not work.

Arithmetic:

String math is not supported by FlashBASIC.

Arithmetic functions may give slightly different results in FlashBASIC. Addition, subtraction, multiplication, division, and remainder (modulo) will give the EXACT results with FlashBASIC as R83. Otherwise, the FlashBASIC compiler results are based on the host machine's internal arithmetic. Any arithmetic functions not listed above use the host machine's arithmetic. If using the (f option, all arithmetic operations use the host machines arithmetic.

Note also, that comparison will not function properly in FlashBASIC if two numbers are compared whose total precision is equal to or excedes 14 digits. Note that one must subtract the current precision from this so that the total precision limit is 10 digits at precision 4.

Parameter Passing:

FlashBASIC passes parameters by reference, rather than copy-restore (except for constants and expressions which are passed by copy). This could cause some problems in certain exception cases. For example, if a subroutine is called with the statement "call x(y, y(10))", where "y" is an array, and within that subroutine y(10) is modified, the current interpreter may restore the value differently than in the compiler.

FlashBASIC allows a maximum of 62 arguments on subroutines.

FlashBASIC does not complain when the number of parameters passed does not equal the number of parameters contained in the subroutine. However, this is NOT supported and can cause subsequent program failure and data corruption.

Arrays:

Array bounds checking is absent in FlashBASIC by default. The "b" option invokes this when compiling. This must be used with caution, as it is easy to destroy other program data due to application bugs.
Syntax
Options
Example
Purpose
Related basic.cfunc.user
basic.cfunc
basic.debugger.overview
basic.execute
access.introduction
basic.call
flash.basic
basic.debugger.down
basic.debugger.up
basic.debugger.
basic.debugger.#
flash.basic.error.logging

compile.time.date.stamp.ap

Command compile.time.date.stamp.ap Definition/BASIC Program
Applicable release versions: AP 6.1, AP 6.0 FlashBASIC
Category BASIC Program (486)
Description contains descriptive internal information about programs compiled for Pick/BASIC and FlashBASIC.

When a program is compiled on Advanced Pick releases of 6.1.0 or higher, information is placed in the dictionary level of the file in which the source program resides. The structure of the information is as follows:

Attr Description
0 item-id
1 CC
2 starting frame number of object code
3 Pick/BASIC object frame count
4 date, internal, when last compiled
5 time in seconds, internal, when last compiled
6 port number of who compiled program last
7 user who compiled program last
8 account name that compiled program last
9 release version from where program was last compiled
10 options used when last compiled, alphabetically
11 bytes in Pick/BASIC object code
12 FlashBASIC object frame count
Syntax
Options
Example
ct dict bp prog

001 CC
002 740380
003 1
004 9424
005 37743
006 12
007 dm
008 qa
009 6.1.0.A5
010 
011 43
012 0

 This program was compiled October 19, 1993 at 10:29:03 a.m., and takes up 43 
bytes of 1 frame. It was compiled on port 12 by user "dm" in the 
account "qa" with no options and was not Flash compiled.
Purpose
Related tcl.basic
ue.222d
tcl.compile
value.mark
pc.d
pc.text.extract
attribute.defining.items
compile.time.date.stamp.rp
flash.basic
tcl.list-obj
access.c/total
access.c/flash
access.c/fid
access.c/size
access.c/date
access.c/time
access.c/port
access.c/user
access.c/acct
access.c/release
access.c/code
access.c/options
access.c/bytes

basic.performance

Command basic.performance Definition/BASIC Program
Applicable release versions: AP 6.0
Category BASIC Program (486)
Description discusses three methods of increasing performance: replacing dynamic arrays with dimensioned arrays, replacing common with named common, saving screen images in a variable.

Replacing dynamic arrays with dimensioned arrays is especially effective when an item is read from a file, and manipulated extensively afterwards. If the number of attributes in the item is known, the "matread" statement may be used to read the dynamic string on disk into a dimensioned array. If the size is not known, or subject to change, read the item into a dynamic array, then use "dcount" to get the number of attributes, redimension a dimensioned array to the desired size, and assign the dynamic array to the dimensioned one. For example:

equ am to char(254)
read xx from "big.item"
size = dcount(xx,am)
dim stat(size)
stat = xx

Another great speed increase can be realized by using named commons to store data that must be used between various applications. See "common" for more information on this topic. If named commons are used for this purpose, all applications involved must be compiled EITHER with the interpreter or with FlashBASIC.

If an application does large amounts of screen output, it is suggested that screens be built as large strings at the beginning of the program. This way, a screen refresh is simply a "print" of a string variable.

x=@(-1):@(1,1):"Name:":@(1,2):"Number:":@(1,3):"Address:"
print x
Syntax
Options
Example
Purpose
Related tcl.compile
tcl.term
tcl.run
basic.common
basic.debugger.down
basic.debugger.up
basic.debugger.
basic.debugger.#
flash.basic.error.logging
tcl.config.core

tcl

Command tcl Introductory/TCL
Applicable release versions:
Category TCL (746)
Description The Pick System Terminal Control Language (TCL) is a system-level command language with system-defined or user-defined statements that can be executed individually or sequentially. System-defined statements are called TCL verbs. User-defined statements are: macros, menus and cataloged Pick/BASIC programs. The first word of a TCL statement must be either a system verb, macro, menu or cataloged Pick/BASIC program.
TCL commands can be typed in when the TCL prompt colon (":") displays. The completed command is entered for processing by pressing <Ctrl>+m or <Return>. Because mistakes do occur, TCL editor and TCL stack facilities are provided.
The TCL editor allows corrections to commands after they are entered, but before they are executed. The TCL stack each command entered at the TCL prompt and allows you to recall commands for correction and/or execution. Refer to the sections "Editing TCL Commands" and "TCL Stack" below and to the entries tcl stack and tcl edit commands for more information.
TCL commands include the Access and Spooler commands. Access is a system-level information retrieval language that allows you to query your data base without writing complex programs. The Spooler commands allow you to control how information is output to the printer.

Editing TCL Commands
The TCL editor uses the Update processor (UP) to enter commands, so the TCL editor commands are similar to the UP commands. A TCL command may be created and edited as if it were a paragraph. Pressing a <Ctrl>+m or <Return> key within the TCL command processes the entry.
The TCL editor is initially in the overtype mode. To toggle between overtype and insert mode, type <Ctrl>+r. The following commands function the same in the TCL editor as they do in UP. Refer to the keyboard template provided later in this section.
<Ctrl>+

b Move cursor up one line.
e Delete to end of sentence (command).
g Move cursor to end of sentence (command).
h Backspace and replaces character with space.
i Go to next tab position on line.
j Move cursor left.
k Move cursor right.
l Delete character.
m Insert mode: processes the entry when the cursor is at the end of a line; inserts a carriage return/line feed when the cursor is within the line.
n Move cursor down one line.
o Delete from cursor to end of word.
r Toggle between overtype and insert modes.
t Move cursor to beginning of command.
u Move cursor to next word.
w Insert single space.
x Exit TCL command and leaves just the TCL prompt.
y Move cursor back one word.
z z Undo last delete.


TCL Stack
When a command is entered at the TCL prompt, the system saves the command in the TCL-stack file of the dm account. In AP, your stack is not terminal dependent. If you leave a terminal without logging off, another user can use the terminal under your user id. This causes the new user to "step-on" the your stack.
Changing any part of a TCL command in the stack, causes that stack entry to be moved to the top of the stack. This feature tends to keep the stack compact. However, the TCL stack does not have a maximum number of entries and can continue to grow indefinitely. Therefore, from time to time, the stack should be pruned either from TCL or by using the update command to modify the actual stack item (u dm,tcl-stack, user.name).
The following commands are used to move through a stack and to retrieve and run previously entered commands:

<Ctrl> +
a Searches for the entered string.
c p (cut and pop) Removes the current TCL command from its present position; places it at the top of the stack.
d Goes back to the previous command in the stack.
e If the cursor is on the first character, deletes the entry from the stack and displays the next command down the stack; otherwise deletes to the end of the command.
f Goes forward to the next command up in the stack.
p Moves a duplicate copy of the current TCL command at the current position in the stack to the top of the stack.
x Clears the displayed command from the screen and moves the pointer back to the top of the stack.
z Goes to the command at the top of the stack.
z a Same as <Ctrl>+a but searches to the top of the stack.


Pushing Levels
The execution of any command or program can be interrupted by pressing the <break> key. When a command or program is interrupted, the system stops execution and saves all parameters so that execution can be resumed exactly where it was interrupted. When a process is interrupted at the normal system level, the system prompts with two colons (::). At this point the command or program is said to be "pushed one level". Up to 16 levels can be pushed. The number of colons in the prompt indicates the number of levels pushed. The normal system level is 1.
To return to the previous level and continue execution of the process at that level, press <Ctrl>+m. To abort the process at the next lower level, use the end command. Refer to the entries level pushing and levels for more information.

Macros
A macro is a process that executes one or more TCL commands. Macros are stored in the master dictionary with the name of the macro as the item-id. The macro processor is provided for simple TCL procedures. In general, complex procedures should be written as Pick/BASIC programs.
When a macro name is entered at TCL, it may be followed by any number of parameters. These parameters are added to the end of the first TCL command in attribute 2 as additional language elements and then passed for processing.
The first line of a macro must contain the character m (modify mode) or n (non-stop mode). Each subsequent line is considered a TCL command. If the m code is used in the first attribute of the macro, the TCL command is displayed so that changes can be made to it before it is executed. If n is used, the macro runs immediately.
A macro may be created with the Update processor or the create-macro verb. The create-macro verb takes the last statement entered at TCL and converts it to a macro. Enter the TCL statement to store as a macro and press <Ctrl>+m. When the cursor returns to TCL, enter:
create-macro macro.name
Note that create-macro sets attribute 1 of the macro to m. As long as attribute 1 equals an m, the macro name must be enclosed in double quotes when entered at TCL. Use the Update processor to replace the m with an n if immediate execution is desired. To create a macro using the Update processor, enter:
u md macro.name
For more information about using macros, refer to the entries macro and create-macro.

Menus
A menu provides a selection of processing choices. Menus are items in the master dictionary. The menu processor automatically formats the menu on the screen and you can then select one of the menu options for processing by entering the option number. The format of the menu item in the md is:
001 me {comments}
002 title
003 option 1
help 1
statement 1
004 option 2
help 2
statement 2.1
statement 2.2
...
Refer to the entry menus for more detailed information.

TCL Verbs
TCL verbs which operate exclusively on files and items use a consistent format to specify the file and items:
tcl-verb file.reference {item.list} { (options) }
The format elements are explained in the Access section below.

Access Verbs
Access is a system-level information retrieval language that allows you to query your data base without writing complex programs. Access uses TCL commands as verbs and displays the results on terminals or printers. Access verbs operate on specified files and items based on optional criteria, specifications, modifiers, limiters, and options.
Often described as an ad-hoc data query language, the greatly expanded dictionary capabilities of Advanced Pick offer the possibility of real nonprogrammer access to the data base. Access, used in conjunction with the Update processor (UP), makes Advanced Pick one of the most accessible data management system in existence.
Additional AP features enhance the already comprehensive query language. Pick/BASIC calls from dictionaries are used for complex data calculations and output formatting. The ss (spread-sheet) connective allows the user to print out Access reports in spread-sheet format. This is achieved by adding the ss connective to the sort sentence and defining the desired range parameters. B-trees have increased the speed and performance of Access.
Access commands are entered at TCL and thus can be recalled, modified, or executed through the TCL stack. Access sentences may also be stored and invoked through macros, menus, PROCs, and Pick/BASIC.
An Access statement has the following form:
verb file.reference {item.list} {selection criteria} {sort criteria} {output specifications} {print limiters} {modifiers} { ( options ) }
The verb and file.reference are required as operator and operand respectively. The verb must be the first word of the command. All other elements are optional and are used to modify either the operator, operand, or output. Selection criteria, sort criteria, output specifications, print limiters, and modifiers follow the item.list and may be in any order. Options, if used, must be placed last and must be preceded by a left parenthesis. The right parenthesis is optional.
Relational operators can be used with any of the elements of Access sentences to allow exact specification of the conditions to be met. Refer to the entry relational operators for more information.
file.reference
Usually the name of a file in the md to which the user is currently logged. It can also be a synonym file name. The file name can be preceded by the literal dict to access the dictionary of the file instead of the data portion of the file. The default is data. In some cases, data may be specified to indicate only the data portion of the file.
To reference a file in another account or md from TCL, pathnames are used. The pathname may be used in place of the file.name in any TCL or Access statement. A pathname may be entered in one of the following forms:
account.name,dict.name,file.name
account.name,file.name,
dict.name,file.name
item.list
Specifies one or more item-ids in the file defined by the associated file.reference. The item.list may be one or more explicit item-ids, a series of items separated by relational operators, an asterisk (*) to represent all the items in the file, or null.
If a select list is not active, a null item-id implies a new item for UP and all items for the other processors. Any command requiring a select list can obtain it from a previously selected list. (See the get-list, select, and sselect commands.) To cause a processor to use the select list, the item.list must be null. An item-id with the same name as a language element in either the md or the dictionary of the file must be enclosed in single quotes.
selection criteria
Limits the data by specifying criteria that must be met. Multiple criteria may be established to limit data selection to meeting a certain set of limitations. These sets are established by the logical relational connectives "and" or "or".
sort criteria
Connectives used to define the sort operation.
output specifications
Specifies the attributes to list. The selected attribute items or synonym labels are displayed in either a columnar or non-columnar format depending on the report width. The width of the report is the sum of the width of each attribute to be listed plus one blank separator between each attribute. If the width of the report does not exceed the page width as set by the term verb, a columnar format is generated.
The attributes for each item are displayed one under the other. If the requested output exceeds the page width, the column headings are listed in a non-columnar format down the side of the output with their respective values immediately to the right. In the non-columnar format, the column headings are listed only if there is a corresponding value. Item-ids are always displayed unless it is suppressed using the id-supp connective.
print limiters
Suppresses the listing of attributes within an item that do not meet specified limits.
modifiers
Control listing parameters such as double-spacing, control breaks, column totals, and suppression of item-ids, automatic headings, and default messages.
(options)
Used to tell the processor about special handling and tend to be processor specific. The options are single alpha characters and/or a numeric range specification as required by the specific processor. They are usually preceded by a left parenthesis. The right parenthesis is optional. When used, options must be the last element on the command line.

Wild Card Capability
Wild card characters may be used to select item-ids and attributes based on common characters. Wild cards can be used in selection criteria or complex item-lists as follows:
[ (left bracket) Matches characters following the bracket. Ignores characters to the left of the bracket.
] (right bracket) Matches characters from the beginning of the string to the bracket. Ignores the characters to the right of the bracket.
^ (caret) Matches any character in the position occupied by the caret.

Retrieval of Items from Files
The Access processor uses both the master dictionary and the file dictionary to determine the definition of the elements in the Access sentence. The file pointer to the file dictionary and the connectives used in the sentence, for example, are found in the master dictionary. The file pointer to the data file and file-specific attribute definitions are found in the file dictionary. If an element is defined in both the master dictionary and the file dictionary, the definition in the file dictionary is used.
If the element is not found in either the master dictionary or the file dictionary, Access creates a new element by concatenating the unknown element to a blank and the next element in the string. The processor attempts to look up this new element in first the file dictionary and then the master dictionary. If the new item-id is not found, an error message displays. The Access processor does not look up terms in the string that are enclosed in quotes, single quotes, or backslashes. These are assumed to be literals.

Default Output Specifications
In addition to explicitly listing attribute names as part of the Access statement, there are three features that can be used to specify default output specifications. These specifications output the default attributes when attributes are not explicitly specified in the Access statement and are listed below:
- The attribute names can be listed as a macro in the file-defining item.
- Default attribute items can be created.
- Temporary attribute items can be created.

Default Attribute Items
Default attribute items have numeric item-id starting with 1. These item-ids are used by Access verbs as output specifications if no other output specifications are given. The numeric item-ids must be consecutive; that is, in order to have the third attribute list by default, attribute items 1 and 2 must exist, even if they are not needed for the listing. The attribute items for attributes that are not needed for listings can be given a d/code of x . For more information about default attribute items, refer to the entries default attribute items (AP), default attribute items (R83), and default output specifications.

Temporary Attribute Items
Attribute items using special attribute names can be specified in an Access sentence without actually existing in either the file dictionary or the master dictionary. The attribute name is of the form "Aac", where 'ac' is the attribute number. Temporary attribute items are created with a justification code (attribute 9) of lx (left justify and expand display field to fill report).
For example, even if neither the master dictionary nor the file dictionary for ent has an attribute-defining item a14, a statement such as "list inv a14" lists attribute 14 in the ent file where inv is the temporary attribute name.

Spooler
The Pick System Spooler controls all output that is sent to the printer. The term "Spooler" comes from the acronym SPOOL derived from Simultaneous Peripheral Output On-Line. Depending on the printer assignments and the status of the printer, the output may be printed immediately, sent to tape, placed in a queue, or placed in a hold file.
Most Spooler commands allow options, which sometimes have numeric arguments. To keep these options clear for the options interpreter, it is recommended that numeric options be separated with blanks as in the following example that assigns for hold file output to formqueue 1 with 3 copies:
:sp-assign 3 hsf1
Spooler options do not have to be enclosed in parentheses like options with other TCL commands. If numeric options are within parentheses, parameters outside of the parentheses will be ignored. Do not separate options with blanks.
The Spooler directs the items in the queue to the printer as the printer becomes available. The Spooler formats items in a hold file as if they were being output to the printer, but does not actually output them. The Spooler can be directed to output hold file items to the printer, to tape, or to a specified file. The following TCL commands are available to control the Spooler activity:

:startspooler assignfq list-ptr
listabs listpeqs listptr
sp-assign sp-close sp-edit
sp-kill sp-open sp-status
sp-tapeout startptr startspooler
stopptr

For more detailed information about these commands, refer to the individual entries for each command.

TCL Commands
The TCL commands are listed below. For a more detailed description of each command, refer to their individual entries.


! :absload :bootstrap
:files :reset-async :scrub-ovf
:shutdown :startspooler :swd
:swe :swx :swz
:taskinit = ?
abs-dump abs.fid absdump
account-maint account-restore account-save
add add-font addbi
addd addenda addendum
addx after alarm
b/list basic basic-prot
beep bformat blist
block-print bootstrap break-key
brk-debug brk-level buf-map
buffers bulletin.board buffers.g
cal capt capture-off
capture-on case case-file
cat catalog cd
cf charge-to charges
check-account check-dx check-files
check-sum check-ws checkfiles
chg-device chksum choose.term
cl clear-basic-locks cleanpibs
clear-file clear-index clear-locks
clock cls cmdu
coldstart coldstart.log color
comment compare-list compare
compile compile-catalog config
conv-case converse copy
copy-list copydos count
cp create create-abs
create-account create-bfile create-file
create-index create-macro create-nqptrs
cross-index cs ct
currency date db
dcd debug decatalog
define-terminal define-up del-acc
delete delete-account delete-file
delete-index detach-floppy delete-list
detach-sct dev-att dev-det
df diag dir
dir.pick disc disk-usage
diskcomp diskcopy display
div divd divx
dl dm dos
dos.bridge dos.shell dos.video
download dtr dtx
dump ecc echo
ed edit edit-list
el end env
environ epson esc-data
esc-level esc-toggle exchange
exec exit export
f-resize fc fdisk
fid file-save filecomp
find fkeys fl
flush font-parms format
frame-fault free fuser
get-list get.pick gl
group halt-system hash-test
help hush import
import.pick indexer init-abs
init-ovf initovf inputwait
inter iselect isselect
istat item k
kill l ld
ldf legend lerrs
lf lfd lfs
li link-pibdev link-ws
list list-abs list-acc
list-commands list-conn list-device
list-dict list-errors list-file-stats
list-files list-item list-jobs
list-label list-lines list-lists
list-lock-queue list-locks list-logoffs
list-macros list-menus list-obj
list-pibs list-system-errors list-procs
list-ptr list-restore-error list-ports
list-users list-verbs listacc
listbi listc listconn
listdict listf listfiles
listfs listprocs listptr
listu listusers listverbs
ll lm load.mon
lock-frame log-msg log-status
logoff logon logto
loop loop-on lp
lq lre lu
maxusers md-restore message
mirror mlist mload
mmvideo modem-off modem-on
mono monitor-status move-file
msg mul muld
mulx mverify nframe-index
node nselect off
okidata op overflow
ovf p pack
password phantom-status pc
pibstat pick pick-setup
pid pitch-compile pitch-table
poke povf power-off
ppcp prime print-err
print-error printronix prio
prompt psh psr
pverify pxpcmd qselect
r83.setup reboot rebuild-ovf
recover-fd recover-item reformat
rename-file renumber reset-port
reset-user restore-accounts ri
rmbi rnf rtd
run run-list s-dump
save save-list search
search-file search-system sel-restore
select send-message set-8mm
set-abs set-batch set-batchdly
set-baud set-date-format set-cmem
set-date set-date-eur set-break
set-date-std set-device set-dptr
set-esc set-file set-floppy
set-flush set-func set-half
set-imap set-iomap set-kbrd
set-keys set-num-format set-lptr
set-ovf-local set-ovf-reserve set-port
set-runaway-limit set-sct set-sct-dma
set-sym set-shutdown-delay set-sound
set-tape-type set-term set-time
set.lptr set.time setpib0
setport setup-printer setup.rtc
setup.sio sh shell
shl shp-kill shp-status
shpstat shutdown si
sl sleep slice
sm sort sort-item
sort-label sort-list sort-users
sortc sortu speller
sreformat sselect stack
start.rtc start.ss startlog
startsched startshp stat
status-port steal-file stoplog
stopsched strip-source sub
subd subx sum
system-coldstart t-att t-bck
t-bsf t-bsr t-chk
t-det t-dump t-eod
t-erase t-fsf t-fsr
t-fwd t-load t-rdlbl
t-read t-ret t-reten
t-rew t-select t-space
t-stat t-status t-unld
t-unload t-verify t-weof
t-wtlbl ta tabs
tandem tape-socket tcl
tcl-hdr term term-type
termp test-cursor time
time-date timedate tlog-restore
to touch trap
txlog type type-ahead
unix unlink-pibdev unlock-frame
unlock-group unlock-item unpack
update update-abs-stamp
update-accounts update-logging update-md
update-prot user-coldstart useralarm
user-shutdown verify-index verify-abs
verify-system vga.lcd video.demo
what where which
which-line who wlist
wselect wsort wsselect
x-ref xcs xonoff
xref xtd z
zh zhs

Connectives
Connectives are words in the master dictionary that are used to form the elements of Access statements. They include relational operators and modifiers and are used to form sort and selection criteria and limit data to be processed by the verb with which they are used.
Relational operators are used to establish criteria based on the relationship of data to fixed values or other data. Relational operators would be used to select a range of zip code values within specified upper and lower limits. Refer to the entry relational operators for more information.
Other modifiers and options are listed below. For more information on each of these connectives, refer to their individual entries.

any before break-on
by by-dsnd by-exp
by-exp-dsnd col-hdr-supp dbl-spc
data entry det-supp dict
duplicate each every
fill footing grand-total
hdr-supp heading header
id-prompt if {each|every} id-supp
if{no} legend-supp lptr
ni-supp no nopage
only or roll-on
sampling spread-sheet ss
supp tape tcl-supp
total total-on using
with within without
Syntax
Options
Example
Purpose
Related

tcl.setup-printer

Command tcl.setup-printer Verb: Access/TCL
Applicable release versions: AP
Category TCL (746)
Description downloads fonts to a LASER printer attached to a formqueue.

The form-queues are items in the "dm,devices," file with fonts 1 through 16 defined at the proper table entry (x-125 through 140.)

The list of font item-ids used by a form-queue are in the file "dict dm,fonts," with the item-ids the same as the form-queue.

If a form-queue is indicated, it downloads the fonts in that list.

If a printer number is indicated, for all form-queues defined by that printer, it downloads the fonts in each form-queue list. Thus, by specifying the item-id of the form-queue, it retrieves the list of fonts in "dict dm,devices,".

"form number" is the form-queue number to which the fonts are downloaded.

"printer number" is the printer number to which the form-queue fonts are downloaded.

Fonts reside in the "dm,fonts," file.

The list of fonts assigned to a form-queue resides in "dict dm,fonts form.queue.number"

Setting up a form-queue downloads all the fonts defined for that form queue.

Setting up a printer does a form-queue download for each form queue defined for that printer.

Each (downloaded) font is stored in the printer's memory, and is referenced by a numeric font-id number. To insure that an existing font isn't accidentally overwritten, the beginning font-number of "10" is used, and is incremented by "10" for each additional downloaded font.

The fonts may be invoked using the same "@" functions available to Pick/BASIC. See the "@ function" and the arguments between (-146) and (-267), or by the OP ".font<font.number>" command.
Syntax
Options
Example
Purpose
Related tcl.download
tcl.add-font
basic.@.functions
font
op.font

ap.overview

Command ap.overview Article/Article
Applicable release versions: AP
Category Article (24)
Description overview of Advanced Pick, The Update processor, and application prototyping considerations.

Contributed by Jim Jobson
(Original article was published in PickWorld under the title, "Why Direct Marketers Choose Advanced Pick: AP's Powerful Data Model, the Update processor and the Ability to Customize are Major Factors")

1. Catalog and Direct Marketing companies have to solve a significant database problem.

2. The Update processor has several qualities which make it more powerful than (Unix) utilities such as vi, including consistency.

3. Terms such as cruising, zooming, double clutching and hot keys are part of an intriguing Advanced Pick vernacular.

4. Advanced Pick is a database environment containing Fourth Generation tools.

5. Applications development in AP is fun because it can be accomplished quickly and easily.

6. Increased productivity will prove to be a selling point in the buying decisions of end-users.

7. Sophisticated users who learn the Update processor appreciate the power that they have over their database.

The Pick System is well known in many vertical markets but is especially popular in the direct marketing and catalog industries. This article is about why the Pick System, and especially Advanced Pick provides the ideal platform for direct marketing, telemarketing, mail order and similar applications. Pick is well suited for many applications outside these arenas; the concepts discussed here will apply to those situations as well.

Advanced Pick makes sense to direct marketers for many reasons, including the AP data model and the rapid applications development environment. Direct marketers have a need for Unix, as well, since direct marketers communicate with electronic devices such as automated credit card authorization services, shipping manifest scales and order taking centers that transmit orders via modem lines.

Most of Rigden's clients are on Unix/Pick platforms. This is an efficient way to go, since all of the applications available to Unix users are now available to Pick users. For example, users need to transmit and receive credit card authorizations from an outside service. The actual data transmissions and receptions are done more efficiently with Unix. Communications are initiated from Act I (in the Advanced Pick environment). The data is exported from AP to Unix. Once in Unix, an application called MLINK transmits and receives data through the modem line. Eventually the data is imported back to AP and the Act I database is updated. Having Advanced Pick work with Unix is valuable in that AP works with any hardware platform that Unix works on.

Companies such as SCO and AT&T have the resources to port their versions of Unix to all the newest hardware technology. This means that Advanced Pick can 'piggy back' to whatever platform makes sense at the time.

The end result is that AP works on the current and fastest machines. It has been estimated that approximately 30 percent of the third party software installations in the catalog industry are running on a Pick System.

One reason is that a major strength of Pick is the data management capabilities that are available. Many argue that in this particular aspect, Pick is superior to anything in the market. I feel that this is an accurate perception, but is even more true in Advanced Pick than with any of the other versions.

Catalog and Direct Marketing companies have to solve a significant data base problem. The direct marketer needs to manage customer, inventory, catalog, pricing, order, financial, list management, sales analysis and many other databases. The customer file alone can be substantial, containing customer inter action and order history, demographics, credit history, segmentation, etc.

Another major reason Pick makes sense for direct marketers is that these companies always need a great deal of development. Enhancements are needed for two reasons. First, direct marketing companies are often unique and creative. They need substantial enhancements in order to get started, because the application is expected to fit the users needs rather than the other way around.

Direct Marketing is an emerging industry and is becoming more of a force all the time. Ideas, rules, methodologies, laws and philosophies are evolving; software needs to be versatile and evolve with the times. Even smaller direct marketing comanies require initial enhancements and on going programming. These type of companies require a system that lends itself to rapid and cost effective customization.

I decided over 4 years ago to build a new direct marketing application (Act I). I chose Advanced Pick as the platform because I saw that two major reasons for Pick's popularity in direct marketing, the inherent database capabilities and built in tools for rapid applications development, are stronger with AP than with any other platform.

The Advanced Pick data model is more robust than any other version, including R83. A few subtle features provide new dimensions and make Advanced Pick a provocative database tool.

In this article I intend on to show that Advanced Pick makes sense to direct marketers because it addresses their needs in a complete and comprehensive manner. Advanced Pick makes sense in many other arenas and the principles described below can be applied to them.

Improvements to the Pick Data Model with Advanced Pick

As in all versions of Pick, Advanced Pick is comprised of files, which are populated by items. The data is described in a dictionary level of the file and natural languages (such as Access) allow the user to manipulate the data. This time proven technology still works wonders, however some additional features greatly enhance an already powerful system.

File-defining item extensions

There are two types of dictionary items in Pick, attribute-defining items and file-defining items. There is one file-defining item for each data file.

The file-defining item has been an integral part of the Pick Data Model from the beginning. On R83 the file-defining item or 'DL' id (for Data Level id) defines the base FID (start ing frame-id for the file), contains the modulo (number of contiguous frames the file was last created with) and allows for file resize definition. These features are still true in Advanced Pick, but the enhancements allow for data to be updated through the dictionaries (as opposed to Pick/BASIC programs).

Advanced Pick is a complete database environment. Much of the data updating in Advanced Pick comes as a result of additional features in the dictionaries and new processing codes. For the first time, updating with Pick comes from dictionary definition and doesn't necessarily require Pick/BASIC programming.

The file-defining item has several attributes which come into play. The correlative (attribute 8) allows the developer to add processing codes, which will be evoked as the item is filed. While some processing codes are only relevant in the context of the Update processor, others will be evoked regardless of how the item was updated. A Pick/BASIC program call can be placed in the correlative. The program will be called when the item is filed and can be used for editing, update historical or other related files, print documents, etc.

The macro (attribute 15) contains a default dictionary list consisting of attribute-defining items. This dictionary list will be evoked when the program is updated (from the 'u' or 'update' verb). Sophistication involves the ability to add a multi-valued list of macros which will be evoked in different situations (based on definition from a Pick/BASIC program from the input conversion).

These 'multiple views' allow the user to see data displayed in different ways for the same data file. The output macro (attribute 16) displays the default dictionary listing when access (sort or list) commands are used. If there is no definition for the output macro, the system will use the macro defining item (attribute 15) to display default access listings.

The input-conversion (attribute 14) can call a Pick/BASIC program from the Update processor. The program will be called before the item is entered (but after it has be accessed). The description (attribute 17) can be used for online documentation of any file or attribute in Advanced Pick.

The file-defining item is used as a centralized description for the default screen parameters and rules for updating a file. This makes it easy for the developer to program and maintain data files for use in sophisticated applications.

Attribute-Defining Extensions

Input-conversion : New correlatives are an important part of attribute-defining items and a new dictionary attribute called 'input-conversion' (attribute 14) has been added to the dictionary. The input-conversion is only meaningful in the context of the Update processor, and is used for edit patterns, display only fields, input rules (such as required fields) and to call Pick/BASIC programs. A Pick/BASIC program call from the input conversion attribute will be evoked as soon as data is entered (into that attribute).

New Processing Codes

New processing codes and the ability to call Pick/BASIC programs (custom processing codes) from dictionaries (both file-defining and attribute-defining items) allow for more functionality with less code than before. A good example is that the bridge correlative (which updates a related file defined by the 'bridge') is evoked any time an item is updated. The bridges and B-trees are maintained by the system regardless of how an item is updated (from Pick/BASIC, editor, Update processor, copy, t-load, etc.). Other processing codes that involve updating include time, date, user and seconds stamps and the item-id correlative. Input conversion processing codes include edit pattern (alpha, numeric, hard coded, etc), numeric range, must-input, character update and many others.

The B-trees (secondary indexed sort files), can be evoked from the Update processor or Pick/BASIC. They allow the user rapid access to the database and are extremely useful in large databases. Even files with several million records can be 'sorted' in a matter of seconds through B-trees. A new feature called 'hot keys' allows the user to call any desired Pick/BASIC program from any data element using only a few simple keystrokes.

The Update processor : Innovation with Advanced Pick

All of the functionality described is connected with proper use by the Update processor. Critics of the Update processor point out that it is not 'pretty' and the scrolling bothers users not yet familiar with this tool. They point out that they can't compete with products built with 'PC Quality' screens, etc. I would like to point out several facts about the Update processor.

The Update processor is a new tool to Pick and is the primary user interface for experienced users on AP. It is not, however a panacea, and other techniques, such as the 'ed' (old editor) and Pick/BASIC programs still work.

The Update processor is not necessarily an end user environment, but consider the functionality of the Update processor and compare it with 'ed'. There is so much more that can be done with the Update processor than with ed, that there is no contest. All of the screen techniques that work with R83 or other versions work with Advanced Pick, as does all R83 functionality, including procs.

Use with 'Traditional' Screens

At Rigden we use an attractive state-of-the-art fixed format screen environment called Symbion. This application was created by Colorado developer Gary Huffer (president of Symbion Corporation) and features PC Quality windows (panels), with on line help, popup panels, pull down menus and action bars, full screen editing with function keys, arrow keys and many other user friendly features.

Symbion does not generate source code, but paints the panels and runs the application through a set of sophisticated parameter tables. Symbion was developed using Pick/BASIC and is portable to all versions of Pick, including Advanced Pick. Mr Huffer agrees with me, that the B-trees, file-defining item extensions and other features make the Advanced Pick data model complete.

At Rigden, we develop the Act I application with the Update processor and 'convert' to Symbion only after the database has been established and proven. Symbion works on all versions of Pick, but because of B-trees and new processing codes, it works best with Advanced Pick. The developer can choose which environment to put end users on, the Update processor or a fancy screen environment such as Symbion. The good news is that both environments work quite well with Advanced Pick.

Update processor as Full Screen Editor

The Update processor is a full screen editor with many word processing type functions. Of course there are many full screen editing products and utilities on every operating system. Unix has for example a full screen editor (referred to as 'vi' or Visual Editor'). The vi editor is unique in terms of functionality as is the Advanced Pick Update processor. Both tools allow for full screen editing of data, including recall and maintenance of the data.

If you think that the Update processor is difficult to learn, then try your hand at vi for comparison purposes. The Update processor has several qualities which make it more powerful than utilities such as vi, including consistency. Most of the functionality of the Update processor works at TCL, document entry, software development (building programs and dictionary items), and data entry with similar functionality.

Consistency between environments means that the Update processor has discovered a sense of economy not often achieved by a product of this magnitude.

Update processor Full screen editor functionality includes :

Cursor movements
Adding/editing text
Deleting text
Exiting and filing items
Cut and paste
Search and replace
Prestore commands
Spelling checker

Using the Update processor, you can move the cursor to any position on the screen; insert, delete, or replace text; cut and paste; search for and replace text; and undo mistakes. A spelling checker is available to check text as you enter it.

The Update processor as a Database Tool

The Update processor also operates as a database tool. This is achieved by using the Advanced Pick data dictionary structure. Virtually all of the full screen and document entry functions of the Update processor are available when using the Update processor in the database environment arena.

The combination of full screen editor and database tool is very powerful as we will see. The ability to define ad hoc data entry routines and to then elegantly peruse the database (with few keystrokes) makes for an extremely useful and provocative applications development and end user environment. Even the terms that have organically arisen from early Advanced Pick users suggest a lively system. Terms such as cruising, zooming, double clutching and hot keys are part of an intriquing Advanced Pick vernacular.

Rapid Prototying

One of the greatest features of Advanced Pick and the Update processor is that applications can be prototyped and built much quicker than in other envi ronments. I will attempt to detail the reasons why this is true. The most efficient way to build applications in Advanced Pick is by using the Update processor as a prototyping tool.

Through skillful use of the Update processor, it is possible to model an application simply by defining the database (creating files and dictionaries). Processing codes and Pick/BASIC programs are added to provide extensions to the application. The application is tested (data is entered) by using the Update processor. Since the Update processor is a system utility and one of the many Pick "natural languages," testing can begin immediately upon defining the data base structure.

Please note that final polish such as "user friendly" screen environments (such as Symbion) are added on top of the data model, but not until the data relationships have been established and proven. The only way to prove a datastruc ture is by using it (entering data).

In Advanced Pick, applications can be built rapidly, with few keystrokes and with very little actual program (Pick/BASIC) source code. It is very simple to build systems in this environment once you have the knowledge. The best way to understand how applications are put together is to build one yourself from scratch. Software development is time consuming and expensive. Generally, developers begin to prototype after needs analysis and system design phases are 'complete'. The system can be developed 'from scratch' (using new code) or by using a Fourth Generation Language, or a combination of coding and 4GL.

Advanced Pick is a database environment containing Fourth Generation tools. In application development scenarios, the initial prototype (complete with data entry screens and reports) is based on the original system design. Once the prototype phase has been achieved, it is often clear that the design (file structure) was flawed and more programming must be done to correct the faults to meet the original specifications. In most instances, users change their minds and come up with new ideas about the application after considerable programming has occurred.

It often takes many attempts at programming and reprogramming before the file structure is stabilized and further stages of development begins. Many companies go broke during this process.

Advanced Pick contains many advantages for the software developer, especially increased productivity. For the end-user, this fact translates to cost effective development.

Let us examine how this works. With Advanced Pick, the developer can reach the prototype phase in a fraction of the time compared to other techniques. This is achieved by skillfully utilizing the Update processor, processing codes such as the bridge correlative, B-trees, Pick/BASIC calls from dictionaries and other functions.

Prototyping may be defined as the development of a database as the first step towards building a complete application. The developer can 'finish' the application with additional sophistication and end-user interfaces (such as screens, windows, menus etc.). The reason that prototyping is so rapid in Advanced Pick is that it only takes a few minutes to create files and dictionaries. Once that is done, it is possible to immediately enter data and test the design. If the file structure is faulty or the developer wishes to experiment with alternative structures, it is possible to reconfigure the database by changing or adding to the dictionaries.

Many alternative database configurations can be tested in a short amount of time. In Advanced Pick there is less need for programs and program code, resulting in less source code than other environments. The cost of maintenance increases in direct relationship to the amount of source code generated.

Much of the 'programming' in the Pick environment has been replaced or simplified with powerful processing codes, invoking operations at the dictionary level, which enables the Pick/BASIC routines to be smaller and more powerful.

The main point is that the developer can quickly build database and update environments without coding. This means that testing can occur almost immediately. Once the database is firmly established, the developer can focus on finishing the application by putting in user-specific functionality.

Applications development in Advanced Pick is fun because it can be accomplished quickly and easily. Productivity is an extremely important factor in direct marketing, but also in any other business arenas. Since software develop ment has always been a costly proposition, increased productivity will prove to be a selling point in the buying decisions of end-users.

End Userablity of the Update processor

As I have pointed out, fancy screen environments are available on Ad vanced Pick and the end user doesn't necessarily have to use the Update Proces sor. Beginning users are often intimidated by the wealth of functionality and control key sequences of UP.

Let's look further at this issue, however. The Update processor is functionally very powerful and should definitely be considered as an end user environment with some, though not necessarily all situations.

At Rigden, we have successfully installed many companies who use the Update processor as the only screen environment and end user interface. We have proven that data entry screens (such as order entry) take only a few hours of training and practice before the user has mastered all that is needed. Sophisticated users who learn the Update processor appreciate the power that they have over their database. I know many users who prefer the Update processor as a screen environment. Admittedly, it took a little getting used to, but once done they have no interest in going back to fixed format screens or whatever they used previous ly.

System Features

The Advanced Pick data model, Update processor and ability to develop applications quickly, are certainly highlights of AP. The complete environment needs to be considered in order to fully appreciate this system.

The following features are all significant factors in terms of increased productivity, and also a fun and easy environment to develop in. There are several features of Advanced Pick that once one understands how to benefit from the features, it is difficult to go back (to whatever else was used before). These features are important to developers because the environment lends itself to higher productivity. It is meaningful to end users because faster programming results in cost effective customization.

One of the most important features is that Advanced Pick works with Unix. This means that AP can work on any environment that Unix works with. The end result is that Advanced Pick, partly due to hardware environments, is much faster than anything previously available.

To log onto Advanced Pick, first logon as a 'user' and then to an 'account'. This is a beneficial feature, known as the double logon. The user logon features the ability to evoke any verb, macro or Pick/BASIC program. This means that it is relatively easy to impose sophisticated security software, since the system access by a user can be controlled by a Pick/BASIC program. The user logon has other implications, most notably, that each file can be stamped with the users logon id. This is valuable in security and other functions such as operator productivity reports. The best thing here is that the developer can define 'user stamps' on any file(s) with a processing code (correlative).

Once logged on to the system, there are other prominent features. The first thing to notice is that Advanced Pick is case insensitive. This means that the user can type in lower or upper case and the system will recognize the commands. This is definitely a big deal. In every other version of Pick or Pick-like products that I have encountered, upper case is dominent throughout the system.

If you don't think this is a big deal, try Advanced Pick for several days, typing only in lower case. You will be surprised how easy it is to convert and then how difficult it is to go back to UPPER CASE ONLY. What a drag.

If you insist on upper case only, no problem. Advanced Pick has a verb 'case-on' that will allow the system to be case sensitive. There is a database for the users (see 'users' file on account 'dm').

This points to another great feature of Advanced Pick, which is that most of the system functions are easily accessed in a database. For example, each user has their own unique 'TCL stack' item stored in the 'tcl-stack' file which brings us to the next valuable function, TCL. Advanced Pick TCL contains the ability to easily recall the last TCL command.

Using the AP fullscreen editor (Update processor), it is easy to search for, recall, modify and execute any TCL command. The TCL item can be deleted or cleared out at any time, at the discretion of the user. I find that an ongoing record of TCL commands is a valuable and time saving development tool. Since the TCL stack is an item in a file, it is easy for the developer to utilize any desired functionality (such as the '.' versions of TCL stack).

Advanced Pick contains many time saving productivity tools. These features include limitless item size, direct pathing (replacing need for Q-pointers), level pushing, shorter and easier syntax ('save-list' and 'get-list' are also 'gl' and 'sl'), and an easy-to-use phantom processor.

There are many other features of Advanced Pick, which make it useful such as the Output processor. New extensions to Pick/BASIC make it a more useful language. I appreciate the 'file' statement which opens and dimensions the file based on dictionary definition. Now even Pick/BASIC uses the dictionaries to the fullest, making Advanced Pick a complete database tool.

The root and key statements allow easy access to B-trees from within Pick/BASIC. As with the rest of Advanced Pick, a much easier syntax is available in Pick/BASIC than in other versions of Pick. Examples are the 'file' command, 'exit' command and simpler 'if' sentence syntax.

In this article, I have attempted to show why Advanced Pick makes sense for direct marketers and other business applications as well. Advanced Pick has powerful database and applications generator features, both of which are impor tant to direct marketers.

The speed of the newest hardware platforms functioning with Unix provides AP users with all the functionality from Pick, Unix and DOS applications (DOS can be run under Unix). All of these features make sense for many vertical and horizontal markets in addition to direct marketing. Rigden developed Act I using the latest tools contained in Advanced Pick.
Syntax
Options
Example
Purpose
Related

tcl.help

Command tcl.help Verb: Access/TCL
Applicable release versions: AP
Category TCL (746)
Description provides an interface to the on-line copy of Advanced Pick Reference Manual version 2.0, printed version.

To fully appreciate and exploit the help system, a working knowledge of the Update processor is required.

Quick command summary:

<ctrl>+xe Exit item.
<ctrl>+n Move cursor down one line.
<ctrl>+m Move to next paragraph.
<ctrl>+b Move cursor up one line.
<ctrl>+p Move to next page.
<ctrl>+ze Move to end of document.
<ctrl>+zy Move to previous page.
<ctrl>+t Move to top of item.
<ctrl>+g Move to end of attribute (paragraph).
<ctrl>+g<ctrl>+g Zoom to related subject.
<ctrl>+f Cruise forward on indexed attribute.
<ctrl>+f Move to next sentence in a text attribute.
<ctrl>+d Cruise backward on indexed attribute.
<ctrl>+d Move to previous sentence in a text attribute.
<ctrl>+e Erase to end of line.
<ctrl>+a Search for phrase or repeat last search.

Hotkeys:

<ctrl>+x4 Preview mode.
<ctrl>+x5 Print hard copy of subject. Use this on this item.

"help" invokes the TCL command, "help.display", and displays a read-only copy of the Advanced Pick document/topic closest to the specified token. If a token is not specified, the "help" token is displayed.

Once inside the help system, the "token" (subject), "category", "type", "description", "syntax", "options", "compatibility", "see.also", "example", and "warnings" attributes are displayed.

"Cruising" through help topics:

You can "cruise" forward with <ctrl>+f or backward with <ctrl>+d on the "token", "category" and "type" attributes. All other attributes are text attributes. In an text attribute, <ctrl>+f moves to the beginning of the next sentence and <ctrl>+d moves to the previous sentence. Cruising on the "token" field is particularly useful. For instance, there are multiple "delete" tokens. If you were to type "help delete", you would arrive on the "first" reference to delete, which happens to be the Pick/BASIC delete function. Issuing a <ctrl>+f while positioned on the token field takes you to the next "delete", which is the Pick/BASIC delete statement. Another <ctrl>+f takes you to the TCL delete verb.

Changing topics:

While on the "token" field, you can change topics easily by typing a new topic over top of the existing word or words, then <ctrl>+e to erase the rest of the line, followed by <ctrl>+f to cruise to the topic. For example, suppose you are in the topic, "attribute-defining items", and you want to see the "list" verb. The screen would look like:

topic attribute-defining items

The cursor is positioned under the "a" in the word "attribute". This is where you type "list", so that the screen looks like:

topic listibute defining items

With the cursor under the second "i" in "listibute. A <ctrl>+e wipes out the rest of the "junk" on the line, so it looks like:

topic list

BEFORE you hit <return>, type <ctrl>+f. This will cruise forward to the first "list" subject found. If you hit <return> BEFORE hitting <ctrl>+f, you can still recover, but you have to re-position the cursor to the end of the token attribute (<ctrl>+b to move up, then <ctrl>+g).

"Zooming" to related files and subjects:

The "category", "type", and "see.also" attributes allow "zooming" to supporting files and subjects. "Zooming" is accomplished with two <ctrl>+g's. The first <ctrl>+g moves to the end of the attribute. The second <ctrl>+g "zooms" to the related file or subject. This is most useful on the "see.also" attribute, which is like a hypertext jump to a related subject in the same file.

To practice "zooming", see the topic "cursor movement" in the "see.also" field. To get to the topic, press <return> until the cursor is on the "cursor movement" topic, then "zoom" to the related topic. When you are done with the topic, <ctrl>+xe returns to the previous topic.

Exiting help:

<ctrl>+xe returns control to TCL, unless you have "zoomed" to one or more related help items through the "see.also" field, in which case, each <ctrl>+xe returns to the previous subject.

"help" invokes the "look-only" mode of the Update processor, which prevents the ability to file any items. This means that you can't hurt anything, in case you accidentally erase or type over part of a help item.

Printing a help item:

Once inside a help item, you can print the item using "hotkey" 5. This is accomplished by pressing <ctrl>+x5. The "hard copy" output is exactly the same as the "preview" mode output.

"Previewing" a help item:

To help distinguish the elements of a help item, we have built a special processing language that affects the syntax. The "preview" mode is activated by "hotkey" 4, (<ctrl>+x4).

The required elements in the syntax are shown in boldface characters. All "fill-in-the-blank" (parameters) of the syntax are underlined in "display" mode and italicized on hard copy. Every element listed in the syntax is either discussed in the "description" attribute, or is listed in the "see.also" attribute. See the topic "documentation conventions" for more explanation on the use of special characters in the syntax.

The "preview" mode uses Access with a number of Pick/BASIC subroutine calls. While in preview mode, pressing any output-producing key on the keyboard advances to the next page. <ctrl>+x returns to the Update processor mode. You can not cruise or zoom while in "preview" mode.

On releases of AP prior to 5.2, there may be a small problem when returning from preview mode. This has to do with the program attempting to store the "zp" (refresh screen) command into the Update processor using the "access(21)" function. This feature was added in 5.2 and doesn't work on earlier versions. Another thing to watch out for is when it DOES work. It has the side effect of loading "zp" into "prestore 0", so that when a <ctrl>+p is issued, it refreshes the screen, rather than advancing to the next page. Use <ctrl>+zn to page down in the item, or redefine prestore 0 to be "zn" using the "zl" command.

Finding an item when you're not sure what you're looking for:

The help system is especially helpful if you know the topic you are searching for, such as the "locate" instruction in Pick/BASIC. Our intent is to help you find your topic within a few hits. For instance, "locate" is one of the "see.also" fields listed under the topic of "statements and functions" in Pick/BASIC. From this topic, you can "zoom" to "locate".

As a last resort, you can use the "search" or "find" commands to search through every help subject for a particular word or phrase. For instance, if you knew that there was a command that produced output in a four-column format, you could use the "search" command on the "ap.doc" file, looking for the string "four-column". (As an exercise, see if you can find at least one subject with the string, "four-column"). For more information on "search" and "find", "zoom" to them through the "see.also" field.

Searching for a word or phrase in a particular item:

In some of the documentation items, the "see.also" field can span many screens. To get to a specific point in the item, the UP search command can be used. For example, in the token "attribute-defining items", a "see.also" is provided to "hotkey9". To get to it in a hurry, use <ctrl>+a. When prompted for the search string, enter "hotkey9" (without the quotes), then press <return>. This searches for the NEXT occurrence of "hotkey9", which it finds in the text. Press <ctrl>+a again and it finds the next occurrence, which is the "see.also" to "hotkey9".
Syntax help {token}
Options
Example
help  

This brings up this help item.

help locate

This looks for the token, "locate", and starts from that point in the 
token's b-tree index.

help fred

This looks for the subject closest to "fred". Since "fred" 
does not exist this should arrive in the topic, "free".
Purpose
Related tcl.help.display
ap.doc.macro.?
up.cursor.movement
tcl.find
tcl.search
ap.doc.function.install.help
installation

basic.quotes

Command basic.quotes Reserved Character/BASIC Program
Applicable release versions: AP, R83
Category BASIC Program (486)
Description marks the beginning or ending of a literal string in Pick/BASIC.

Generally, it does not matter which types of quotes are used on literals (strings). Some instructions, such as "heading" and "footing", impose certain restrictions on their use.

If a literal string is to contain a single-quote, it must be enclosed within double-quotes (") or backslashes ().
Syntax [|'|"]string[|'|"]
Options
Example
if answer = 'quit' then stop

In this example, single quotes are used to determine if the contents of 
"ANSWER" contains the literal string, "QUIT".

heading "'lc'Pick Systems'l'"

This example illustrates the use of two types of quotes, which happen to be 
enforced by the "heading" statement. see "heading".

execute list entity heading "'lc'Entity'l'"

Access sentences enforce the rule that the "heading" string must be 
enclosed in double quotes. "heading" options must be enclosed in 
single-quotes ('). The whole string is passed as a literal by enclosing it 
in backslashes ().
Purpose
Related tcl.conv-case
basic.casing
basic.
string.expressions
basic.footing
basic.'
basic."

UE.4193

Command UE.4193 User Exit/PROC
Applicable release versions: R83 3.1, R83 3.0, R83 2.2
Category PROC (92)
Description disables output to the spooler, and redirects output to the terminal.

Called from PROC, this performs the exact same process as "printer close" in FlashBASIC or Pick/BASIC. Its function is to 'close' the currently open print job and direct subsequent output the the terminal.
Syntax
Options
Example
Purpose
Related proc.user.exits
ue.0193
basic.printer
basic.debugger.p
system.debugger.p
ue.8193

basic.cfunction

Command basic.cfunction Definition/BASIC Program
Applicable release versions: AP/DOS, AP/Unix
Category BASIC Program (486)
Description provides access to C libraries from Pick/BASIC.

Three libraries are defined. "unix.builtin" and "gm.builtin" are provided as part of Advanced Pick. "user.builtin" is provided for user-written C routines.

If only the C programs defined in the "unix.builtin" libraries are used, the "cfunction" statement is optional. If user-defined or third party C programs are used, the "cfunction user.builtin" statement is required.

C program availablility is dependent upon the version of AP used:

unix.builtin Available on Unix-based versions of AP
c.builtin Available on DOS-based versions of AP
user.builtin Available on Unix and DOS versions of AP
Available on all versions of AP

The "user.builtin" table is maintained with the "addbi" TCL command.
Syntax cfunction name {, name ...}
Options
Example
cfunction unix.builtin
cfunction user.builtin, gm.builtin
Purpose
Related basic.statements
basic.cfunc
basic.cfunc.user
basic.%close.apdos
basic.%open.apdos
basic.%read.apdos
basic.%write.apdos
tcl.addbi.apdos
tcl.addbi.unix
basic.%alarm
basic.%chdir
basic.%chown
basic.%close
basic.%creat
basic.%fclose
basic.%fgetc
basic.%fopen
basic.%freopen
basic.%fdopen
basic.%fprintf
basic.%fputc
basic.%free
basic.%fsize
basic.%getpid
basic.%getpgrp
basic.%getppid
basic.%ioctl
basic.%kill
basic.%lseek
basic.%malloc
basic.%memccpy
basic.%memcpy
basic.%pause
basic.%pclose
basic.%pgetpid
basic.%popen
basic.%putenv
basic.%read
basic.%semctl
basic.%semget
basic.%setflush
basic.%shmget
basic.%shmdt
basic.%wait
basic.%write
basic.cfunc
basic.%chmod
basic.%dup
basic.%fgets
basic.%fputs
basic.%getenv
basic.%shmat
tcl.addbi.unix
basic.execute.unix
basic.%lseek.apdos
basic.%whex
basic.%rdhex
basic.%memxcpy
basic.%listen
basic.%gethostid
basic.%open
basic.%connect
basic.%socket

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

basic.execute.unix

Command basic.execute.unix Statement/BASIC Program
Applicable release versions: AP/Unix
Category BASIC Program (486)
Description executes a Unix command from within Pick/BASIC.

Any valid Unix command may be executed through the standard Pick/BASIC "execute" statement. By using the format, "!Unix.command", it is not necessary to create Unix verbs in a Pick md.

The variable specified by "capturing" receives the information normally directed to "stdout". Each line is separated by an attribute mark. There is no limitation on the size of the captured data. Unix tabulations characters are not replaced. To replace tabulations, use pr(1), for instance, as a filter (see example below). "stderr" remains associated to the user's terminal.

To capture the ouput normally directed to to "stderr", the standard Unix shell syntax may be used to redirect "stderr" to "stdout" as in the example below:

execute 'cc -o mypgm mypgm.c 2>&1' capturing cc.result

See the Unix User's Reference Manual for information about sh(1).

The variable specified by "returning" receives the exit code of the "Unix.command". If the command cannot be executed, the first value returned is "-1", followed by a space and the decimal value of the error code, "errno", in the range 0 to 255.

Currently, AP implementations do not allow reading data which has been stacked by a previous Pick/BASIC "data" statement.
Syntax execute "!Unix.command" {capturing variable} {returning variable}
Options
Example
The following is an example of a simple file transfer: 

import
001 *
002 ! Copy a file from Unix
003 tclread line
004 line=trim(line)
005 if line='' then goto usage
006 *
007 uname=field(line,' ',2)
008 pfile=field(line,' ',3)
009 pname=field(line,' ',4)
010 if uname='' or pfile='' or pname='' then goto 
usage
011 open pfile
012 *
013 execute '!exec cat ':uname capturing item
014 write item on pname
015 stop
016 *
017 usage:*
018 crt 'Usage: import unixfile pickfile item' 

The "cat" Unix command copies a file to "stdout", which is 
"captured".

To expand the tabulations into the appropriate number of spaces to set 
tabulations to columns 5, 9, etc.. replace line 13 by (for example): 

execute '!exec cat ':uname:' | pr -t -e4 ' capturing item 

Note in this example the usage of "!exec Unix.command" to avoid the 
creation of an intermediate shell.
Purpose
Related basic.cfunc
basic.execute
basic.cfunction
basic.%popen
basic.system

basic.execute.apdos

Command basic.execute.apdos Statement/BASIC Program
Applicable release versions: AP/DOS
Category BASIC Program (486)
Description allows the execution of any valid MS-DOS command from Pick/BASIC.

Most MS-DOS commands may be "executed" (taking memory restrictions into account) using the standard Pick/BASIC "execute" statement directly by placing the "!" in front of the command.

AP/DOS does not currently support capturing output from an MS-DOS command with the "capturing" clause, like in the standard "execute" syntax. DOS output may be redirected using a "redirection clause" in the MS-DOS command.

AP/DOS does not allow stacked data by a previous Pick/BASIC "data" statement to be used as input for an MS-DOS command either. To use stacked data for an MS-DOS command, write the data to an MS-DOS file and then use the MS-DOS redirection clause within the "DOS.command".
Syntax execute "!DOS.command"
Options
Example
include includes fcntl.h
include includes errno.h 
max.sz = 1024 
dat = str(' ',max.sz) 

* Execute the command with the '>' redirection clause.
* This creates the file 'dir.tmp' which contains the
* output of the 'dir' command.
execute 'dir > dir.tmp' 

* Open the DOS file to be read.
fh = %open('dir.tmp',O$RDONLY,0)
if fh < 0 then print 'error opening: dir.tmp' ; stop 

* Read the DOS file.
rc = %read(fh,dat,max.sz)
if rc < 0 then print 'error reading: dir.tmp' else dat = dat[1,rc]
....
* Use the data that was read from the file into 'dat'
....
* Close the DOS file.
rc = %close(fh)
if rc < 0 then print 'error closing: dir.tmp'
end 

! Sample program to use a previously created file to be used
! as stacked data for an MS-DOS command. 

include includes fcntl.h
include includes errno.h
....
* Create the data, 'dat', for the file 'link.tmp' in here.
....
dat = dat:char(26)
max.sz = len(dat) 

* Open the file where the stacked data is going to be stored.
fh = %open('link.tmp',O$TRUNC+O$CREAT+O$RDWR,S$IREAD+S$IWRITE)
if fh < 0 then print 'error with open: link.tmp' ; stop 

* Write the stacked data to the file.
rc = %write(fh,dat,max.sz)
if rc < 0 then print 'error with write: link.tmp' 

* Close the DOS file.
rc = %close(fh)
if rc < 0 then print 'error with close: link.tmp' ; stop 

* Execute the command using the redirection clause '<'.
execute '!link < link.tmp'
end
Purpose Executes the specified "dos.command" from within a PICK/BASIC program.
Related basic.execute
basic.cfunc

ap.dict.sub.calls

Command ap.dict.sub.calls Article/Article
Applicable release versions: AP
Category Article (24)
Description using the "call" statement from dictionaries.

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

This article will show the reader how to call a subroutine from the file-defining item (aka "d-pointer") and the attribute-defining item. It will also explain when the calls take place. Emphasis will be placed on the special relationship that exists between the Update processor (UP) and the new "access" function in Pick/BASIC.

With a Pick/BASIC subroutine call from a dictionary, the access function allows the subroutine to interrogate and/or modify data from the calling environment. This means that the Update processor can pass data as well as other specifications pertinent to the calling environment to a subroutine. The subroutine can then perform any action required, including modifying the data, before returning control of the item to the Update processor.

See the "access (Pick/BASIC: Function)" for a complete list of the expressions available with the access function.

Pick/BASIC subroutine calls from the file-defining item:

From the file-defining item, subroutines can be called from the correlative and input-conversion dictionaries.

DICTIONARY-CODE
BASE
MODULO
STRUCTURE RETRIEVAL-LOCK
UPDATE-LOCK
OUTPUT-CONVERSION
CORRELATIVE call file.time.subroutine
ATTRIBUTE-TYPE
COLUMN-WIDTH
INPUT-CONVERSION call before.update.subroutine
MACRO
OUTPUT-MACRO
DESCRIPTION
REALLOCATION

Note that the syntax for calling a subroutine does not specify any parameters. However, when a subroutine is called from the file-defining item, the entire item body is passed as a parameter.

When a subroutine is called from input-conversion of the file-defining item, control passes to the subroutine before the operator gets into the file via the Update processor. That is, after the UP command has been executed (:u filename) and before the user can get access to the item. This is where access(18) can be assigned a value determining which "view" of data UP dis plays.

When a subroutine is called from the correlative field of the file-defining item, control passes to the subroutine at file time. In other words, when the item is filed by UP, the subroutine is called. The entire item body is passed to the subroutine. Any wrap up file time processing could be done here.

Pick/BASIC subroutine calls from the Attribute-Defining Item:

From Attribute-Defining Items, Pick/BASIC subroutines can be called from output-conversion, correlative, and input-conversion.

DICTIONARY-CODE
ATTRIBUTE-COUNT
SUBSTITUTE-HEADER
STRUCTURE
RETRIEVAL-LOCK
UPDATE-LOCK
OUTPUT-CONVERSION call output.subroutine
CORRELATIVE call preprocessing.subroutine
ATTRIBUTE-TYPE
COLUMN-WIDTH
INPUT-CONVERSION call after.input.subroutine
MACRO
OUTPUT-MACRO
DESCRIPTION

Subroutines called from OUTPUT-CONVERSION are executed on output. Subroutines called from the CORRELATIVE are executed prior to processing. Subroutines called from INPUT-CONVERSION are executed after input.

Let's look at an example of a "customer" file which calls several Pick/BASIC subroutines from both the file-defining item (see Figure A) and the attribute-defining items (see Figure B).

Figure A

customer 'customer'

DICTIONARY-CODE d
BASE 10193
MODULO 67
STRUCTURE
RETRIEVAL-LOCK
UPDATE-LOCK
OUTPUT-CONVERSION
CORRELATIVE call cust.update
ATTRIBUTE-TYPE l
COLUMN-WIDTH 10
INPUT-CONVERSION call cust.setup
MACRO date name phone.number type terms name phone.number
OUTPUT-MACRO
DESCRIPTION
REALLOCATION

Figure B
DICT customer

ac attr-name ty cw input-conversion correlative out-conv

file customer L 10 call cust.setup call cust.update
1 date r 8 d2/ d
2 name l 25
3 phone.number l 15 call phone
4 type l 15 call get.terms
5 terms l 15

To demonstrate the interaction of UP with Pick/BASIC, we will step through the UP command:

update customer

The first thing that happens after the operator hits return, is that the subroutine "cust.setup" is executed:

subroutine cust.setup(item)
item = access(3)
if access(16) then ; * check if this
* is a new item
item<1> = date() ; * put todays date in
* attribute 1 on new
end
*
if system(29) then
user.format = 3
end else
user.format = 2
end
user=field(output,' ',user.format)
if user = "th" then
access(18) = 1 ;* Update processor uses
* macro value = 1
end else
access(18) = 2 ;* Update processor uses
* macro value = 2
end
return ;* return to Update processor

This program puts the system date in attribute 1 if the item being edited is new (using access(16)). It will then decide which "view" of the attributes to be used for updating, depending on who the user logged on happens to be. system(29) returns a '1' if the 'who' command is in R83 format. In AP, the format of the 'who' verb returns port#, user id, master dictionary.)

If the user 'th' is logged on, the Update processor will display the attributes:

date
name
phone.number
type
terms

For all other users, UP will display the following attributes:

name
phone.number

For our example, let's assume that the user is "th". The operator then enters the name and phone.number. On output, the subroutine "phone" is executed.

subroutine phone(value)
item = access(3)
value = item<3>
if value then
if value matches "10n" then
formatted.phone.number = oconv(value,"mr(#3/#3-#4)")
value=formatted.phone.number
end else
inputerr 'Enter phone number with area code and no characters. '
item = ''
end
end
return

This program validates the phone number that was typed in. If entered in error, the subroutine will return control to UP, along with an error message. Otherwise, the phone number will be formatted on output.

Next, the operator types in the "type". The "type" is validated by the sub routine "get.terms". This program also puts a value in the "terms" attribute.

subroutine get.terms(type)
if access(16) then
item = access(3)
type=item<4>
if type matches 'n' or type matches 'p' or type matches 'c' then

begin case
case type = 'n'
term = "net 30"
case type = 'p'
term = "prepay"
case type = 'c'
term = "cod"
case 1 ; term = ""
end case
item<5> = term
access(3) = item
return
end else
inputerr 'Invalid type, must be n, p, or c. Please re-enter. '
item = ''
return
end
end
return

Note that access(3) can be on either side of the equal "=" sign. Access(3) can ONLY be on the left side of the "=" sign when called from input-conversion. When access(3) is on the left of the equal sign, data is passed from the program to the file. When access(3) is on the right side of the equal sign, data is passed from the file to the program.

Now that all the fields have been entered, let's see what the screen looks like:

customer NEW ITEM size 10
date 27 Jul 1991
name Pat Hale
phone.number 714/555-1212
type n
terms net 30

Next, the item is filed. When the item is filed, the subroutine "cust.update" is called.

subroutine cust.update(item)
last.up.command = access(19)
if last.up.command = 'n' then return
if access(12) then
inputerr 'You cannot delete items from this file!'
return
end

equate vm to char(253)
item=access(3)
if dcount(item<1>,vm) > 1 then
inputerr 'Multi-valued names are not allowed '
return
end
return

This routine will return to UP if the operator is requesting a new item. It will then check of the operator is deleting a customer. If so, he/she will be put back into UP and told that customers can not be deleted. The subroutine will then check to see if more than one name was entered in the "name" at tribute. If so, an error message will print and they will be put back in UP. If there were no errors, then the item will be filed.
Syntax
Options
Example
Purpose
Related

basic.debugger.de

Command basic.debugger.de Command/BASIC: Debugger
Applicable release versions: AP, R83, AP 6.0 FlashBASIC
Category BASIC: Debugger (38)
Description invokes the system (virtual) debugger from the Pick/BASIC.

Issuing a "g" command from the virtual debugger returns control to the Pick/BASIC debugger.

The "de" command is identical to the "debug" command at TCL.
Syntax
Options
Example
*de
!g
*
Purpose
Related basic.debugger.overview
basic.debugger.off
system.debugger.g
basic.debugger.d
basic.debugger.debug
tcl.debug
system.debugger.functions

flash.basic.error.logging

Command flash.basic.error.logging Definition/BASIC Program
Applicable release versions: AP 6.0 FlashBASIC
Category BASIC Program (486)
Description describes how to record compiling errors when using FlashBASIC.

When compiling ("flashing") Pick/BASIC programs with the "o" option, the compiler automatically logs all compilation errors, if there is a data section called "$log" present in the user's Pick/BASIC program file. The log is updated ONLY when errors occur. Each log entry's id is the same as the id of the item being compiled.

The first attribute of the entry consists of the time and date that the error occurred as well as the "phase" of compilation where the error occured. Other attributes may contain additional undefined information which may contain Unix error messages.

Errors logged as "phase 0" errors are problems detected by the standard Pick/BASIC compiler. Errors logged as "phase 1" and higher are Flash compilation errors. Errors occuring higher can indicate an installation problem or lack of some resource, such as swap space. In these cases, attributes 2 and higher contain more exact error reporting.

For example, to enable logging for a file called "bp", type the following:

create-file bp,$log 7

From then on, all compile's which use the "o" option will log errors into the "bp,$log" file and may be displayed by typing:

ct bp,$log
or
list-item bp,$log
or
sort-item bp,$log
Syntax
Options
Example
Purpose
Related tcl.compile
tcl.basic
flash.basic
flash.basic.differences
basic.performance
flash.basic.$log

tcl.rmbi

Command tcl.rmbi Verb: Access/Unix
Applicable release versions: AP/Unix, AP/DOS
Category Unix (24)
Description removes one or more functions from the list of Unix or C built-in functions.

"function.list" is a list of one or more item-ids (separated by spaces) indicating functions to add to the existing built-in functions.

Functions in the "function.list" list are no longer available to be called from within Pick/BASIC. If "function.list" is not specified, then a list is presumed to be active. If no list is active, the file-defining the user built-in functions is rebuilt to match the list of built-in functions.
Syntax rmbi {function.list}
Options
Example
Purpose
Related tcl.addbi.unix
basic.cfunc
tcl.set-cmem
active.list
tcl.addbi.apdos
tcl.listbi
tcl.rmbi.link

flash.basic

Command flash.basic Definition/BASIC Program
Applicable release versions: AP 6.0 FlashBASIC
Category BASIC Program (486)
Description converts Pick/BASIC source code into a list of binary instructions called object code.

The "run" verb initiates a program called an interpreter which reads these instructions one at a time and executes the desired actions. Taking this interpretive approach provides swift translation from the Pick/BASIC source, platform independence, small object size, and reasonable performance.

If better performance is desired, the Pick/BASIC compiler can produce "FlashBASIC", or native assembly code from a standard Pick/BASIC object. This FlashBASIC code may subsequently be run in the Pick environment in the same manner as a regular Pick/BASIC program with the exception that FlashBASIC code runs significantly faster.

The "o" option with the "compile" or "basic" verbs invokes FlashBASIC. When complete, the native code produced is appended to the standard interpreted object code. Because FlashBASIC generates machine-specific code, such code must be recompiled when moved to a different platform. Furthermore, FlashBASIC code cannot call interpreted code, or vice-versa. In other words, if a mainline program is compiled with the "o" option, all of its subroutines or "entered" modules must also be created as FlashBASIC.

Choosing a FlashBASIC Level:

The "o" option may be followed by a number, from 1 to 9, which indicates the FlashBASIC (optimization) "level". If not specified, the level defaults to 1, which gives a large performance increase while minimizing compile time and object size. Higher levels increase object size by as much as 100% over that achieved with level 1, and increase compile time exponentially. Furthermore, levels above 1 yield relatively small performance increases for most applications. High levels also tend to use very large amounts of Unix swap space. If the system runs out of swap space, FlashBASIC retries with a lower level. Line numbers (for error messages) and the state of variables within the debugger are also not guaranteed when using a level greater than one. Finally, the exact behavior of a specific level above one is undefined and may be different on different platforms or releases.

Pick Systems advises running routines with various levels to see if the run-time performance increase is worth the compile-time and object-size trade-offs. The best candidates for higher levels are small modules (less than about 200 lines) which have little or no string manipulation and lack significant amounts of screen or disk I/O. Using a level of 9 can cut in half such programs' run time as compared to their speed at level one, while not taking an unreasonably long time to compile.

Producing FlashBASIC without source:

FlashBASIC may be used on an application lacking source code by using the "w" option when compiling (see "compile" for specific instructions.) Therefore, an applications vendor need not ship source code or even a new version of the object code. Customers equipped with FlashBASIC can compile their current applications "as-is". However, it is suggested that future applications be shipped with a Pick/BASIC program, PROC, or macro, that automatically produces the FlashBASIC code at the customers site.

Shipping FlashBASIC code is only recommended when a vendor wishes the code to run on a single platform, and when media size is not an issue.

Compiler Options for use with FlashBASIC:

b Array bounds checking is off by default with FlashBASIC. (It is always generated in the interpreter.) Using the "b" option while compiling adds this feature to the FlashBASIC code, but increases compile time by about 20%, and slows down run-time array accesses.

c Eliminates EOL's (end-of-lines) in both FlashBASIC and interpreted code. Using this with FlashBASIC decreases compile time by 20%, and decreases run-time slightly. However, this prevents the ability to single-step in the debugger.

f Uses floating point arithmetic

h By default, the FlashBASIC compiler attempts to create native code that can be shared by all users. Using the "h" option forces the module to be loaded locally, and is typically used for modules that will be used by only one or two people at any given time.

k This option, when used without the "h" option, forces shared code to remain loaded until the machine is shut down. This option should be used for programs needed by most users of the system. It reduces memory usage and load time drastically when applied to multi-user situations. See the "shpstat" program for monitoring the status of shared programs.

o Triggers the FlashBASIC compiler.

w This option is used when producing FlashBASIC code without source.

Performance Tips for FlashBASIC:

To obtain the best possible run-time performance and compile-time, Pick Systems advises breaking up applications into many small modules. FlashBASIC removes the traditional run-time overhead of large numbers of call's and is able to create more efficient code when the modules are smaller. Furthermore, an application broken into several small modules takes considerably less time to compile than the same application stored in a single item.

The Pick/BASIC "@(x,y)" function speeds up from 10-20 times if the "term" definitions are compiled with the "o" option. For instance, if the current terminal is an IBM 3151 terminal, the "term ibm3151 (co" command compiles and produces FlashBASIC code for the terminal driver. This creates a hidden module for use with FlashBASIC code. For best results, use this feature with high baud rates and/or fast display devices.

Avoid user exits. Standard Pick/BASIC routines compiled with FlashBASIC will probably run just as fast, and possibly faster, than the same routines coded in virtual assembly.

Avoid disk I/O. If an application has read-only tables, it is best to read them all into memory at the beginning of the program rather than reading them piece-meal throughout execution. When reading an item, do a "matread" into a dimensioned array, rather than using several "readv's".
Syntax
Options
Example
Purpose
Related tcl.compile
compile.time.date.stamp.ap
basic.debugger.$!
flash.basic.differences
flash.basic.error.logging
basic.debugger.?!
basic.debugger.return
basic.debugger.#
basic.debugger.?
basic.debugger.c
basic.debugger.k
basic.debugger.l
basic.debugger.n
basic.debugger.help
basic.debugger.down
tcl.config.core
<ctrl>n

programming.using.up

Command programming.using.up Article/Article
Applicable release versions: AP
Category Article (24)
Description short discussion on using the Update processor for programming in Pick/BASIC.

Contributed by Terri Hale
(Original article was published in PickWorld)

If you have Advanced Pick (AP) and you are a programmer, consider using the Update processor (UP) to build your Pick/BASIC programs. (Note: The verb "ed" does not exist in my vocabulary anymore. Why? Read on.)

UP is a full screen editor, unlike 'ed', which is a line-editor. This means that you have full text editing capabilities within your Pick/BASIC programs.

All of the UP commands for moving the cursor and text are available. Some of the most commonly used commands in writing programs are listed in the following table:

mark beginning of text to cut <ctrl>+cd or <ctrl>+cl
mark end of text to cut <ctrl>+cc
paste cut text <ctrl>+cp
read cut text from specified item <ctrl>+cr
write cut text to specified item <ctrl>+cw
load prestore buffer <ctrl>+zl
read saved prestore command <ctrl>+zr
write prestore command to a file <ctrl>+zw
execute prestore command <ctrl>+p
sentence forward and backward <ctrl>+f, <ctrl>+d
word forward and backward <ctrl>+u, <ctrl>+y
character forward & backward <ctrl>+k, <ctrl>+j
delete character <ctrl>+l
go to top of program <ctrl>+t
delete word <ctrl>+o
delete sentence <ctrl>+e
delete program <ctrl>+xo
redisplay screen <ctrl>+zp
display columnar positions <ctrl>+zc
undo previous delete (aka: oops!) <ctrl>+zz
page forward <ctrl>+zn
page backward <ctrl>+zy
toggle insert / overtype modes <ctrl>+r

UP has two modes, insert and overtype. When UP is initially entered, it is in overtype mode.

There is a prestore processor available with AP which is quite a sophisticated programming language in and of itself. There is no limit to the number of prestore commands available. Prestores can be saved in any file on the system and recalled as needed. (See the article in the March/April 1992 issue of Pickworld titled 'Advanced Pick Prestore Commands' for more information on prestore commands.)

Level pushing, or the ability to suspend your program and go list a dictionary or look at another program, is a handy tool to use in writing programs in AP. Level pushing is available from anywhere in AP, not just in the Update processor.

There are several ways to exit a Pick/BASIC program from UP, as shown i the following table:

exit without filing <ctrl>+xe
exit and file changes <ctrl>+xf
exit, file changes, compile & catalog <ctrl>+xc
exit, file changes, compile & run <ctrl>+xr
exit, rename the item & file <ctrl>+xi
exit and go to a new item (program) <ctrl>+xn
exit out of a list back to TCL <ctrl>+xk
exit and return to previous item <ctrl>+xb

Unlike R83, you do not have to file, compile, catalog and run your program with separate editor and TCL commands. In UP, you can do it all with two keystrokes from within the program itself. This is a great time-saver.

Subroutines can be called from within a Pick/BASIC program either at the time the program is filed or anytime during the update session. A subroutine can be called by putting "call subroutine.name" in the file-defining item of the Pick/BASIC program file on the correlative field (file time processing) or on any of the hotkey fields (for in-line program calls). To call a Pick/BASIC subroutine from within a program use <ctrl>+x0-9. A handy use for a subroutine call from a Pick/BASIC program file is to record the time, date and user who updated the program.

Programs can be entered in either upper or lower or mixed case. You never have to hit the caps lock or shift key.

In AP, the TCL verbs "compile" and "basic" behave differently. When you exit a Pick/BASIC program using either <ctrl>+r or <ctrl>+c, the compile form is used.

The "compile" verb is case-insensitive. This means that the variable names, TOTAL, total, and Total will all evaluate to the same symbol. So beware, if you are using the compile verb on programs written in R83 Pick with variable names in both upper and lower case which have different meanings.

On the other hand, "basic" compiles the source code with case sensitivity in effect. This means that the variable names, TOTAL, total, and Total will evaluate to three different symbols.

There are many features available in the Update processor which make writing, compiling and executing Pick/BASIC programs easier, faster and a lot more fun.
Syntax
Options
Example
Purpose
Related

basic.retrieval.locks

Command basic.retrieval.locks Definition/General
Applicable release versions: AP, R83
Category General (155)
Description overview of restricting access to accounts or files.

If any process, such as a TCL command or a Pick/BASIC program is executed from an account that does not have retrieval and/or update privileges for a file, and then attempts to read and/or write to that file, the process terminates with an error message indicating that the file is "access protected".

To read from or write to a retrieval/update protected file, the retrieval and update lock codes must match those of the file that is opened. This is a system function and cannot be accomplished from Pick/BASIC. If the file is retrieval protected, the file cannot be opened and the program will terminate.
Syntax
Options
Example
list payroll

At "tcl", the following message occurs if "payroll" is 
access protected.

[210] File 'payroll' is access protected.

file payroll

If a file called "payroll" has an access retrieval lock which does 
not match the lock codes (keys) for the current user, this statement aborts the 
program with the following message:

[210] in program 'enter-payroll', File 'payroll' is access 
protected.

open 'payroll' to payroll.file else stop 201,'payroll'

If the file is access protected, the "else" clause is taken and the 
following message prints:

[201] 'payroll' is not a file name.
Purpose
Related file.lock.codes
retrieval-lock
basic.update.locks
locks
filename.users
tcl.create-account
ulk

cfunc.load

Command cfunc.load C Function/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description is an optional function for pre-loading FlashBASIC subroutines, before they are needed.

The number parameter must be a pointer to an integer. This integer MUST contain -1 when loading a new subroutine. Upon successful load, this location will contain an index number which should be passed down to succeeding _CP_call's to the same subroutine. This index allows the system to jump directly into the subroutine code without having to look up the name in the master dictionary.

The name parameter should be a CPSTR* pointing to the subroutine name.

The subroutine to be called MUST be previously compiled with FlashBASIC and be cataloged in the current master dictionary.

This function returns -1 if an error occurs. The error code is contained in _CP_errno. Specific error codes include:

PE_LOAD_ERR indicates that the system could not load the subroutine. The subroutine must be cataloged, and must be compiled with the current version of FlashBASIC.
Syntax int _CP_load(int* number, CPSTR* name)
Options
Example
/* call a user-written routine */

CPSTR * s = _CP_mkstr("hi");
int i = -1;

r = _CP_load(&i,s);
if (r < 0)
{
_CP_logoff();
exit(-1);
}
/* Now that the subroutine is loaded, it can be called */
/* very efficiently                                    */

for (j=1; j < 100; j++)   _CP_call(&i,s,0);
Purpose
Related cfunc.introduction

preface

Command preface Introductory/Access: Modifiers
Applicable release versions:
Category Access: Modifiers (8)
Description presents an overview of the Advanced Pick Reference Manual

How to Use This Book
REF is organized into two sections as described below:

Section 1: Overview
This section presents an overview of the Pick System. Included is an introduction to Pick and discussions on data management, the Terminal Control Language, the Update and Output processors, processing codes, and Pick/BASIC. This section is especially useful if you are new to Pick. Refer to the Table of Contents to help find a particular topic.

Section 2: REF
The body of REF presents a reference for all system commands, statements, verbs, functions, and terminology, and complements the on-line version of REF. Information about all versions of Pick (from R83 to Advanced Pick) is included in this section. Whether you are an experienced user or are new to Pick, use this section to reference information about a specific topic.
Information contained in this section is arranged in an encyclopedia-type format. Entries are ordered in ASCII order with the first entry being ! and the last entry being _. A partial ASCII table (from ! to _) is shown below. Use this table help find a particular entry:
Dec Key Dec Key Dec Key Dec Key

33 ! 49 1 65 A 81 Q
34 " 50 2 66 B 82 R
35 # 51 3 67 C 83 S
36 $ 52 4 68 D 84 T
37 % 53 5 69 E 85 U
38 & 54 6 70 F 86 V
39 ' 55 7 71 G 87 W
40 ( 56 8 72 H 88 X
41 ) 57 9 73 I 89 Y
42 * 58 : 74 J 90 Z
43 + 59 ; 75 K 91 [
44 , 60 < 76 L 92
45 - 61 = 77 M 93 ]
46 . 62 > 78 N 94 ^
47 / 63 ? 79 O 95 _
48 0 64 @ 80 P

Notation Conventions
The following notations are used throughout this book:
"text" Quoted text has special meaning. It is often another token (subject) defined in this book.
bold Words or characters in boldface are commands, file names, options, and other keywords recognized by the system. Within a command syntax, bold words are words that must be entered exactly as they appear.
italics Used within paragraph text, certain words are italicized for emphasis. Used within a command syntax, words in italics are parameters to be replaced by an actual value, name, word, or number.
{size} Used within a command syntax, parameters shown within braces are optional.
x{x...} The "ellipsis" (series of three dots) indicates that the information may be repeated one or more times.
x | y Used within a command syntax, parameters separated with a vertical bar are choices.
{x | y} Used within a command syntax, choices shown within braces are optional. One can be selected, but all are optional.
[x | y] Used within a command syntax, choices shown within brackets indicates that one of the elements is required, but not both.


Ordering Additional Reference Manuals
Direct orders for additional manuals to:
Pick Systems
1691 Browning
Irvine, CA 92714

Attention: Order Entry

714/261-7425
714/250-8187 (FAX)

Reader Comments
Pick Systems welcomes your comments about Advanced Pick and this Reference Manual. Your suggestions will help us to maintain and improve our products and publications.
Please mail or fax your comments to the attention of Pick Systems Customer Service at:
Pick Systems
1691 Browning
Irvine, CA 92714

Attention: Customer Service

714/261-5308 (FAX)
Syntax
Options
Example
Purpose
Related

tcl.dev-att

Command tcl.dev-att Verb: Access/TCL
Applicable release versions: AP
Category TCL (746)
Description attaches an unattached port to the current process. This command only changes ownership and is required prior to using the "get" or "send" statements in Pick/BASIC.

The user gets exclusive ownership of the attached port. No other processes are allowed to attach the port until the owner releases the port.

The port is detached by using the TCL verb "dev-det", or by logging off.

If the target port is not linked to the current process, the target port must be unlinked by the "unlink-pibdev" command, or use the (U) option to force the unlink.

Attaching to a device the current process is linked to does not remove that link.
Syntax dev-att port.number
Options U Unlink the target device if required. Attachment fails on a linked device, unless the current process is linked to it.
Example
dev-att 3
Device # 3: Attached to Pib # 0

This attaches port 3 to process 0 (zero).
Purpose
Related tcl.link-pibdev
tcl.dev-det
tcl.unlink-pibdev
basic.get
basic.send
tcl.tandem
tcl.converse
tcl.:ent-list
tcl.:ent-mon
tcl.:ent-status

tcl.shpstat

Command tcl.shpstat Verb: Access/TCL
Applicable release versions: AP 6.0, AP 6.1
Category TCL (746)
Description examines or changes the status of shared Pick/BASIC programs that have been compiled with FlashBASIC.

The default behavior of "shpstat" is to list the status of all FlashBASIC programs currently running in shared memory. The following statistics are displayed:

"Block" is the memory block number.

"Usage" is the total number of users currently executing the program.

"Size" is the total size (in bytes) of the memory block.

"Name" is the Pick/BASIC program name. If the memory block is available, this column displays "( free )".

At the end of the listing, the following statistics are shown:

Free. This gives the total free space in shared program memory. Initially, this number should be slightly smaller than the number specified in the "pick0" configuration file. A program requires a contiguous block of memory to load and free space may become fragmented. Therefore, a given program may not load even though the total amount of free space seems sufficient.

"Max Free" is the largest contiguous free block available to the system. Since FlashBASIC programs must be loaded into a single block, this indicates the maximum size of a program that can be accommodated at the present moment.

"Used" is the total number of bytes used by all shared loaded modules. Use this to determine the amount of shared Pick/BASIC space required. Initially, the machine should be booted with a large shared memory space, then brought up to normal usage. The total shared memory may then be examined. Then, shut down the machine, resize the "basic" option in the "pick0" file accordingly, and reboot. The basic shared memory segment should now be properly sized for your system.

If "shpstat" is invoked with the "l" option, the list is displayed interactively with the following added options:

< Scrolls back one page.

> Scrolls forward one page.

i Initializes shared program memory. This should be used only in the event of serious problems. It completely cleans out shared program memory, causing any users currently executing within it to abort.

k Kills a module. This option is used to free a module from memory if no one is currently using it, to free up some shared space. Any users executing a module which is killed will display "undefined behavior", which could involve aborting.

q Quits the program.

r Refreshes the screen to reflect the current memory status.

s Sets the sleep period in between updates. Smaller sleep times will give a more accurate view of system performance, but will also use more resources.

The program displays some useful statistics at the bottom of the screen:

"Current Page". This shows part of the program list that is currently being displayed.

"Total Number of Pages" is the number of screens the entire list takes. "<" and ">" scrolls through the pages.

"Sleep Time" is the current sleep period in seconds.

To reduce fragmentation, "sticky" programs start loading at the high end of shared memory, while "non-sticky" programs load at the bottom. Often-used programs may be compiled with the "k" option to make them "sticky".
Syntax shpstat {(options)}
Options i Initializes the entire shared program status area. This should be used only in case of emergencies. It causes all programs running in the shared area to abort. When used with this option, "shpstat" clears the memory and completes. No status information is displayed.

l{number}

Loops on displaying status information. This repeatedly updates the status information displayed on the screen. The default time between updates is 5 seconds. The "l" option may be followed by a number to override the default delay time between loops.

p Directs the output to the system printer, via the Spooler.

s Suppresses detail output when used without the (l option (6.1.0 and above only).

z "Zaps" shared program memory. This is a stronger version of the "i" option.
Example
shpstat (l1

This causes the status program to redisplay the current status of shared 
programs every second.  This setting causes a very noticeable drain on system 
performance and should only be used when tuning or if problems occur.

shpstat (i

This completely reinitializes memory.  This may be used if  several processes 
running shared code have aborted abnormally, and the shared memory table seems 
corrupted.  Signs of corruption include long wait times when loading programs, 
and having "shpstat" with no options seem to hang indefinitely.

shpstat
Block  Usage   Size  Name
1      1    106k  REPORT.bp eep.help
2      1     15k  REPORT.bp eep.security
3      1      3k  REPORT.bp btree.root
4      1      8k  cmarc.library cbw.open
5      1     18k  cmarc.library cbw.place
6      1      7k  cmarc.library cbw.box
7      1     27k  REPORT.bp eep.format.doc
8         2,374k  (free)

Free:  2,374k     Max Free:  2,374k     Used:    185k
Purpose
Related tcl.term
tcl.run
tcl.config.core
tcl.syschk

cfunc.call

Command cfunc.call C Function/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description is equivalent to the FlashBASIC statement: call name( {string1 {, string2 {, ...}}})

The number parameter must be a pointer to an integer. On the first call to particular subroutine, this integer MUST contain -1. Upon successful return, this location will contain an index number which should be passed down to all succeeding _CP_call's to the same subroutine. This index allows the system to jump directly into the subroutine code without having to look up the name in the master dictionary.

The name parameter should be a CPSTR* pointing to the subroutine name.

The subroutine to be called MUST be previously compiled with FlashBASIC and be cataloged in the current master dictionary.

The expression must be the number of parameters to pass.

Each parameter passed to FlashBASIC must be a CPSTR**. Upon return from the subroutine, FlashBASIC will reconvert its variables back to strings, if necessary, and stuff the results back into the passed CPSTR**'s.

This function returns -1 if an error occurs. The error code is contained in _CP_errno. Specific error codes include:

PE_BAD_PARAMS indicates that too many parameters were passed as expression. The user may only pass _CP_MAX_PARAM parameters.

PE_LOAD_ERR indicates that the system could not load the subroutine. The subroutine must be cataloged, and must be compiled with the current version of FlashBASIC.
Syntax int _CP_call(int* number, CPSTR* name, int expression, { CPSTR** string1 {, CPSTR** string2 {, ... }}})
Options
Example
/* call a user-written routine */

CPSTR * s = _CP_mkstr("hi");
int i = -1;

r = _CP_call(&i,s,0);
if (r < 0)
{
_CP_logoff();
exit(-1);
}
/* Now that the subroutine is loaded, it can be called */
/* very efficiently                                    */

for (j=1; j < 100; j++)   _CP_call(&i,s,0);
Purpose
Related cfunc.introduction

pc.ms

Command pc.ms Processing Code/Restore Processor
Applicable release versions: R83 2.2, AP
Category Restore Processor (84)
Description used to alter the normal sort sequence of characters.

Used to sort an attribute in a sequence specified by the item called "seq" in the "messages" file (or "errmsg" file in R83). This is only used on an attribute defined as a sort key, thus, this code must be applied as a correlative (attribute 8). Not available for use in Pick/BASIC.

The "seq" item must be manually added to the "messages" file using the following suggested format for the item:

seq (item-id)
001 !"#$%&'()*+,-./0123456789:;<=>?@ABC
DEFGHIJKLMN OPQRSTUVWXYZ[]^_`abcde
fghijklmnopqrstuvwxyz{|}~
Syntax
Options
Example
Purpose
Related processing.codes
output-conversion
ue.1072
seq
pc
pc.o

r83.to.ap.2

Command r83.to.ap.2 Article/Article
Applicable release versions: AP
Category Article (24)
Description identifies differences between R83 and AP, part 2

Contributed by Ron Davis
(Original article ran in PickWorld Magazine)

If you are new to Pick, and don't have an existing R83 database to convert, but wish to convert a non-Pick system to Advanced Pick, then this article is not for you. That essentially involves designing and duplicating an existing application on a new platform. Such a discussion is way beyond the scope of this article. Instead, we will talk about the typical R83 system which will be upgrading to Advanced Pick.

Porting Your Programs and Data

Porting your system over to Advanced Pick should not pose too great a problem. In a nutshell, here is what you will have to do: * Save your current system's programs and data in a form that will be readable by your new system, * Load the programs/data into your new system, * Perform 'update-account' on each of your ported accounts, * Resolve any inconsistencies that may have popped up, * Compile your programs.

Saving Your Current Pick Data

You will need to consider that your system is made up of several components:
* Pick Systems software. This software is to be replaced with the new Advanced Pick software. If you are currently using Pick R83 or Pick OA, then they are compatible. If you are using a Licensee version of R83, then there may be verbs that will no longer be available.

* Other Commercial software. If you are currently using Jet, AccuPlot, Mainlink, or other commercial software, then you will probably wish to have them on your Advanced Pick system as well. Contact your Pick dealer to see about relicensing fees or repurchasing the product(s).

* Custom (purchased) Software. If you are using custom-written software from a vendor company, you may not have the source code available. You will have to contact them to obtain a new version of their software for Advanced Pick, or for relicensing fees.

* Your application procs and Pick/BASIC programs. If you are currently using Pick R83 or Pick Open Architecture (OA), then your procs and Pick/BASIC source programs should be compatible. However, the object code is not compatible, so you will have to port the source code over, and compile it on the new system. To save time and grief, decatalog the object code so you don't even bother trying to port it over.

* Your assembly language programs. Any assembly language programs you have will almost assuredly have to be re-written in Advanced Pick Assembler. Please contact your Pick dealer as the Advanced Pick Assembler Account is a separate product.

* Your data files. Nearly all Pick systems, whether they be licen sees or the real thing, have the same data structure (values, attributes, segments), so you shouldn't need to do anything to them. However, do not forget any files or procs you may have lurking in the SYSTEM dictionary or the SYSPROG account.

Data Exchange Media

Consider that you need some media that will be common to both your systems -- your current system and your new one. The most likely methods of data exchange involve: * Diskettes * 1/4" Tape Cartridges * 1/2" 9-Track Tapes We will consider all of these as "magnetic media," as they have common formats and problems.

In converting, you must consider the mechanisms themselves. Some may work only at certain densities. Others may be incompatible with mechanisms of a different manufacture. If you are going to use the same equipment, then the problem of compatible mechanisms is no longer a concern. However, the format of the data on the tape still must be reckoned with.

ACCOUNT-SAVE For Pick Licensee systems (Ultimate, Reality, Fujitsu, etc.) you will have to check your manuals to see if the ACCOUNT-SAVE format is compatible with Pick.

T-DUMP If your system cannot generate a Pick-compatible ACCOUNT-SAVE, then you will have to save your system with a series of T-DUMPs. Since you may blanch at the idea of T-DUMPing several hundred files, please refer to the December 1986 issue of PickWorld, which contains an article by Lawrence DeAngelo titled "File Transfer Tricks: A Useful Tape Program" on pages 10 and 11. It shows source code to generate a series of T-DUMPs on a single tape (on the R83 side), and a routine to automate the T-LOAD procedure (on the Advanced Pick side). Tape labels and Blocking factors across all the different ver sions of Pick are notoriously non-uniform. Please check your Pick manuals for more information.

Advanced Pick supports a diskette blocking factor of 500 (only), with a tape blocking factor of up to 16,384. Note: Earlier R83 releases have had difficulties dealing with multi-reel file saves on 1/4" tape. There is no dependable way to insure that Advanced Pick will be able to properly restore such a tape, so keep your saved data to a single tape. If a full file-save won't fit on one tape, then do a series of ACCOUNT-SAVEs, each with their own tape. If it still won't fit, then consider a series of T- DUMPs. Play it safe. Make at least two copies. You'll never forgive yourself if you experience a media failure.

* Serial Data Communications Ports.

Another alternative would be to transfer the data between 2 operational computers (one being the "old" existing system and the other being the "new" AP system) via RS232 ports using a data communication product, like Via Express, or Laguna Connection, PK Harmony, Mainlink, or whatever. This will involve a lot of time as a 19,200 baud port isn't as fast as a Cartridge Tape. (Plan for data exchange rates of about 7mb per hour, tops.) Don't forget, you will need the communications product on both machines. Talk to your Pick dealer about licenses.

* Another possibility is to use the R83 verb EXPORT to transfer data from the Pick partition into the MS-DOS partition. You can then use the AP verb import to pull the data into the AP file. However, at the time of this writing, this option is currently not available across all Advanced Pick platforms, as some of them are unable to access a DOS-format diskette. If you aren't planning on having similar media capabilities on your new machine as the old one, then you may wish to consider a media transfer service - a company which will convert your data to a new media for a fee.

Pick Systems has some limited file transfer capability, and may be able to help you with this. Contact Pick Systems for more information. If you are coming from a licensee version of Pick, then there may be data layout differences, making the ACCOUNT-SAVE compatible with Advanced Pick. It would be safest to assume the worst, and make T-DUMPS as well as the ACCOUNT-SAVES, in case the ACCOUNT-SAVEs are not readable. Check your files' master dictionary attribute-1 (LIST-ITEM MD filename). Files that are specified as 'DX' or 'DY' will not be saved. You'd better check and make sure nothing crucial is being left out.

NOTE: If your old computer system is going away for good, or you are wiping out your existing computer system to reload the new Operating system, then it is ABSOLUTELY VITAL that you have a dependable way of reading the backup media, as you can't go back to the machine and try again. It is STRONGLY suggested that in such cases, you make both ACCOUNT-SAVEs and T-DUMPs in at least two different kinds of media (like magtape and diskettes). As mentioned before, make sure you have more than just one copy, and that the media is reliably readable. This data is your lifeblood. Don't risk it.

Loading Your Data to AP

Loading your data into AP can take one of only a few forms:

* Performing a full file restore from a previous AP system, or
* Performing a series of account-restores from tape.
* Create the accounts, and restore from tape by doing either: sel-restores, or t-loads.
* Create the accounts, and upload the files through an RS232 port.
* Create the accounts, and import the files from another partition.

Setting the restore device

Use the 'set-device' or 'set-sct', or 'set-floppy' command to set the proper media device for restoring. * Depending on the format of your ACCOUNT-SAVE, you may have to do: set-sct (block.size). If your ACCOUNT-SAVE is from R83 v2.1 or earlier, then use 'set-sct (r)' for "reverse" compatibility with older tape formats.

file restore If you are coming from an existing Advanced Pick system, then do not use the '(D)ata files' option for restoring the system. This will "restore" the 'dm' account as well, which would be ill-advised.

restore-accounts. The most popular method of restoring data is the 'restore-accounts' command. It performs a series of account-restores -- one for each account it finds on tape that isn't already on the system.

* Do: 'restore-accounts' to restore every account on tape that doesn't already exist on the system. The restore-accounts command has options available which help it to read some licensee FILE-SAVE tapes. restore-accounts (c) "Compatible" mode. Tape is in "Ultimate" format. restore-accounts (u) Tape label is in "Ultimate" format. Once it has completed restoring all of the accounts, you must still perform the 'update-account' command for each of the newly-restored accounts. See below for information on 'update-account'.

account-restore. To transport a single account, use the 'account-restore' command.

* account-restore (origin.system.frame.size) lets you set the frame size of the original system, if it is different from your Advanced Pick system.

* Do not restore any system accounts such as 'dm', 'spooler', or 'qa'.

* Do: 'account-restore account.name' for each account to be restored. Depending on the format of your ACCOUNT-SAVE, you may have to do: 'account-restore account.name (as)' instead. When it has completed restoring the account, you must still perform the 'update-account' command. See below for information on 'update-account'.

create-accounts. If you are not using 'account-save' or 'file-save' tapes, then you will have to create each account and file manually (See the 'create- account' and ' 'create-file' commands for more information) and port the data over file by file. (Keep in mind that Advanced Pick's frame size may be two to four times larger than your "old" system, so you will have to adjust your modulos accordingly). Once the files are created, you can load your files by: * doing 't-load's, or * Using a terminal emulator software package to "upload" the files using a serial RS-232 port, or * Using the 'import' command, copy the data from a "foreign" (DOS or Unix) filesystem.

Update-account

Once all the programs and data are safely in their accounts, you must run a "scanning" program which looks for possible problems and inconsistencies in the account.

Do the following: * 'update-account account.name' to update the verbs in the account. It will scan through the account's files, and insert the new expanded information into the dictionaries. As it goes along, it may find verbs or procs or subroutines that it cannot resolve into an Advanced Pick form. It will place these problem children in the 'dm > clashes,account.name' file. It will be your responsibility to resolve these inconsistencies.

The 'dm > clashes,account.name' file contains a list of all of the problems that the update-account processor encountered as it tried to update the files, procs, and etc. up to AP. This is a post-mortem analysis area, not a repair-and go routine. Possible sources of clashing: Licensee verbs (or verb options) that don't exist in AP. Licensee HUSH/NOHUSH does not exist in AP (use 'echo') Licensee PERFORM does not exist in AP (use 'execute') Licensee user-exits may work differently or not be supported on AP Licensee BLOCK-PRINT works differently from 'block-print' Licensee IF-THEN-ELSE correlatives and on and on... Repeat this for all of your accounts.

Other Files You Need to Restore or Create

If you are porting your data from OA, then have no fear. You are already used to the Advanced Pick environment. But don't forget a couple of important files:

* Any files or procs in the SYSTEM dictionary ( "mds" ).
* The 'dm' account: 'dm > abs' (Custom abs files) 'dm > bp' (Pick/BASIC programs) 'dm > users' (User logon / password / permissions file) 'dm > devices' (Terminal / printer devices in the system) 'dm > fonts' (Printer fonts file) 'dm > iomap-file' (Keyboard definition) 'dm > kb.pc' (Keyboard definition) 'dm > kb.fk' (Function keys) 'dm > messages seq' (The method of sorting for the 'ms' correlative) 'dm > messages legend' (The legend printed at the bottom of reports) 'dm > pibs' (The pibs file) 'dm > tcl-stack' (The users' TCL command stack) 'dm > md coldstart' (Coldstart macro) 'dm > md system-coldstart'(Coldstart macro) 'dm > md user-coldstart'(Coldstart macro)

* Possibly, the 'pa' and 'qa' accounts.

If you are coming from an R83 environment, you will need to re-arrange a few files from the R83 SYSPROG account, and put them into the AP-equivalent 'dm' account:

* 'SYSPROG COLDSTART' to 'dm > system-coldstart' 'System-coldstart' is a macro, so it should contain an 'n' in attribute-1, and the following lines are TCL commands needed to start up your system. Here's a sample of the files:


: list-item md system-coldstart
001 n
002 run dm,bp, start.ss
003 init-ovf
004 run bp cleanpibs
005 run dm,bp, start.rtc
006 coldstart.log
007 term-type
008 set-abs dm,abs, (s
009 coldstart
010 off

: list-item md coldstart
001 n
002 run dm,bp, user.coldstart
003 off

: list-item bp user.coldstart
001 !
002 * user's coldstart procedure for setup
003 *
004 casing off
005 open 'md' else stop 201,'md'
006 readv any from 'user-coldstart',1 then
007 chain 'USER-COLDSTART'
008 off

: list-item md user-coldstart
001 n
002 run dm,bp, setpibs
003 startspooler (c
004 assignfq 0,hp.laserjet.IIp,1,epson.mx80
005 startptr 0,0,1,p0 (s
006 startptr 1,1,0,p1
007 off

* 'SYSPROG USER-COLDSTART' to 'dm > users' The 'users' file is a file of user.id's, so each user may have their own separate logon procedure. Or, if you want, all the separate user.ids may each call the same macro to set up their environment. Here is a sample user.id :

: list users donna
name Donna Davis
address 1691 Browning Ave.
zip 92714
phone 714-261-7425 714-250-8187 fax
phone.id dd
keys admin sales
password FFA08438
privilege sys2
options n
macro run bp choose.term
legend-on
set-sym gsym
logto admin

* 'SYSPROG' procs to 'dm' Since you will not be restoring the SYSPROG account, you need to save all of your R83 procs. A typical way to do this is to save them (on the R83 system) to a T-DUMP: : SSELECT MD WITH A1 = "PQ" : T-DUMP MD * And then you may easily restore them (to the AP system) with a t-load: : t-load md * Warning: There may be procs with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a proc because it had the same name as an existing proc. If you do a 't- load (o)', then you run the risk of overwriting a crucial Pick-supplied proc. You may wish to restore them one by one.

* 'SYSPROG BP' to 'dm > bp' In addition, you may have Pick/BASIC programs residing in SYSPROG's 'bp' file which need to be moved over. Again, you can use the T-DUMP / t-load method to restore the programs. Warning: There may be programs with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a program because it had the same name as an existing program. If you do a 't-load (o)', then you run the risk of overwriting a crucial Pick-supplied program. You may wish to restore them one by one.

* 'SYSPROG CURSOR' to 'dm > devices' The 'devices' file contains the output control commands for output devices, namely, terminals and printers. This lets the Output processor change fonts and display styles. The 'devices' file already contains items for many of the popular terminals and printers, so all you probably have to do is to insure that your terminal and printer devices are listed. However, you may have specific terminal defini tion items in your 'SYSPROG CURSOR' file which may not be in Advanced Pick's 'dm > devices' file. If so, you can resort to using the T-DUMP / t-load method to restore them. Warning: There may be definitions with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a terminal definition because it had the same name as an existing one. If you do a 't-load (o)', then you run the risk of overwriting a crucial Pick-supplied terminal definition. You may wish to restore them one by one. If your device is not listed among the entries, then you will have to choose a suitable substitute from the available choices, or create a new entry. For terminals, use the familiar define-terminal program to create a new terminal device. For printers, also use the define-terminal program to create a new printer device. * In addition, there may be some files residing in the 'SYSTEM' dictionary which you will need. If so, then T-DUMP them as well.

Compiling Pick/BASIC Programs

After you have restored all your data onto the AP system, you will have to recompile your Pick/BASIC programs. A typical command would be: : basic bp *

Be on the lookout for compilation errors caused by non-Pick licensee problems, such as: HUSH/NOHUSH (use: echo on/off) INCLUDE item.name FROM file.name (use: include file.name item.name) PERFORM (use: execute)

Assembling User Exits

In addition to compiling your Pick/BASIC programs, you will have to re-assemble your assembly language routines. The assembler is considerably different from R83, so you may even need to rewrite some of your code to get it to function properly.

Commercial Software Considerations

If you have Jet, Accu-Plot, Desqtop, Mainlink, or any of the other commercial software available for Pick, you will probably have to obtain that product for your new Advanced Pick system, or perhaps pay a new licensing fee. Contact your Pick dealer for details.

Custom Software Considerations

If you are using custom-written software from a vendor compa ny, you may not have the source code available. You will have to contact them to obtain a new version of their software for Advanced Pick. If the Pick/BASIC source code is not available, then you have one last hope: a de-compiler. This is a program which reads the object code (on your "old" system) and produces source code (on your "old" system). There are a few that have such packages available, or provide a de-compiling service for a fee. Check your PickWorld magazine or Pick HITS catalog for possible references.

A SAMPLE UPGRADE SESSION

What follows is a sample checklist to upgrade from, say, R83 v3.1 on a 386 computer to Advanced Pick/Native v5.2.0 on a different 386 computer.

On the R83 machine:

1) For the SYSTEM account, do: * Examine the account for DX'ed or DY'ed files. LIST MDS WITH A1="DX" OR A1="DY" Edit the files appropriately. * Save any non-Pick files: LISTFILES SYSTEM (pick which ones you want to save, and) T-DUMP MDS filename * Save the procs (if any). SSELECT MDS WITH A1="PQ" T-DUMP MDS *

2) Find out what accounts are on the system. LISTFILES SYSTEM An alternative command to use would be: LIST-FILE-STATS (This is especially useful if you will have to create the files on the AP side.)

3) For the SYSPROG account, do: * Examine the account for DX'ed or DY'ed files. LIST MD WITH A1="DX" OR A1="DY" Edit the files appropriately. * Save any non-Pick files: LISTFILES (pick which ones you want to save, and) T-DUMP MD filename * Save the procs (if any). SSELECT MD WITH A1="PQ" T-DUMP MD * * Decatalog any Pick/BASIC programs in the BP file you need, and then save the file. DECATALOG BP * SSELECT BP * T-DUMP BP * * Confirm that the save is reliable. Verify the save using 'T-VERIFY account.name (AEFPT)', or using the "dummy" 'SEL-RESTORE non.existent.account (F)'.

4) For all other non-Pick accounts, do: * Examine the account for DX'ed or DY'ed files. LIST MD WITH A1="DX" OR A1="DY" Edit the files appropriately. * Decatalog any Pick/BASIC programs. DECATALOG basic.file * * Save the account. SAVE account.name (DFIPST) * Confirm that the save is reliable. Verify the save using 'T-VERIFY account.name (AEFPT)', or using the "dummy" 'SEL-RESTORE non.existent.account (F)'.

5) Do steps (1) through (4) twice, so you have two sets of backups.

On the AP machine:

6) Install Advanced Pick on the target machine as per the Installation Guide.

7) Customize the 'dm' account. * Coldstart routines * User logon items. * Terminal and Printer devices. * Custom procs. * Custom programs.

8) Restore each account. * Restore the account account-restore account.name 500 (z) * Update the account to Advanced Pick format. update-account account.name * Resolve any problems encountered and logged to the 'dm > clashes,account.name' file. * Compile any Pick/BASIC programs (items). basic file.name * Resolve any compile errors you might get.

9) At this point, the system is upgraded to Advanced Pick. Run whatever test routines you need to run to make you feel confid ent in the system's operation.

10) Relax.

Hopefully, this checklist will help you perform a smooth and orderly transition from your R83 system to Advanced Pick. The final installment of this series, to be published in the next issue of PickWorld, will go over the fine points of moving an Advanced Pick system to a different Advanced Pick platform.
Syntax
Options
Example
Purpose
Related tcl.set-break

UE.6193

Command UE.6193 User Exit/BASIC Program
Applicable release versions: R83 3.1, R83 3.0, R83 2.2
Category BASIC Program (486)
Description removes all but the last three characters from the data passed from Pick/BASIC.
Syntax results = oconv( string.expression, 'u6193')
Options
Example
string = "abcdefghixyz"
string = oconv(string,'u6193')

In this example, the results of the conversion call would be "xyz"
Purpose
Related proc.user.exits
ue.a1a2
proc.ri

basic.@AM

Command basic.@AM Function/BASIC Program
Applicable release versions: AP 6.2
Category BASIC Program (486)
Description returns a string containing an attribute mark.
Syntax @AM
Options
Example
Purpose
Related basic.statements
basic.functions