logical.expressions.in.acodes Article/Article, v/typ Attribute Defining Item/BASIC: Syntax, tcl.blkio Verb: Access/TCL, attr.type Attribute Defining Item/BASIC: Syntax, perf Definition/General, access.sellist Definition/Access: Verbs, sdb Definition/Unix, tcl.set-ovf-local Verb: Access/TCL, justification Attribute Defining Item/BASIC: Syntax, compile.time.date.stamp.rp Definition/BASIC Program, system.security.article Article/Article, pc.d Processing Code/Restore Processor, system.debugger.dfs Definition/System Debugger, access.introduction Introductory/Access: Verbs, at Attribute Defining Item/BASIC: Syntax, general.blocked.io Definition/General, access.c/bytes Attribute Defining Item/BASIC: Syntax, up Introductory/Update Processor, basic.access Function/BASIC Program, access.^ Modifier/Access: Verbs

logical.expressions.in.acodes

Command logical.expressions.in.acodes Article/Article
Applicable release versions:
Category Article (24)
Description constructing logical expressions in "A" processing codes.

contributed by Malcolm Bull. Original article ran in PickWorld Magazine.

In terms of value for money, the A processing code is unrivaled on R83, and is beaten only by the Advanced Pick CALL processing code, as discussed elsewhere in this issue. The A code can perform the actions of a great many other codes:

A1:" ":2 is equivalent to C1;" ";2

A2["1","3"] is equivalent to T1,3

A(1+2)/(3-4) is equivalent to, and considerably easier to write than F;1;2;+;3;4;-;/

and together with the additional fact that the A code can itself directly apply other conversion codes:

A(2*3/"100")(MD2) A3(G1*1)(MTS) A4(G3 1)(MCT)

give it tremendous power.

In this article, I want to look particularly at the logical capabilities of the A code. This form of the A code allows logical comparisons or tests to be made, and a value of 1 (=true) or 0 (=false) will be returned according to the result of that comparison. For example, the code:

A4=5

would return a value of 1 (true) if attribute 4 of a data item were equal to attribute 5, otherwise a value of 0 (false) would be returned. Another example:

AN(QTY)>"0"

would return a value of 1 if the QTY is greater than 0, otherwise a value of 0 will be returned.

In the logical A code, the operators are:

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

The logical A code can be used as shown here to output a value of 1 or 0, but there are ways of exploiting this further. One possible application might be in a situation where it is required to display today's date if attribute 7, say, were blank, otherwise to display the data held in attribute 8. This might be achieved with a processing code such as:

A(7="")*D+(7#"")*8

If the result were to be further converted to external Date format, this code could be modified to:

A((7="")*D+(7#"")*8))(D)

This will only work successfully for numeric data. For general data, we might use the form:
A("HIGH"["1",(2>5)*"99"]):("OK"["1",(2=5)*"99"]):("LOW"["1",(2<5)*"99"])

On implementations such as Reality and Ultimate (and AP. ed.), the AIF correlative offers alternative means of testing data values and taking appropriate action. For example, the correlative:

AIF 2<5 THEN "LOW" ELSE "OK"

will compare the contents of attribute 2 with those of attribute 5 and output either the word LOW or the word OK according to the result of the comparison. We might need this in a situation where attribute 2 contains the actual stock level of our products, and attribute 5 contains the minimum permissible stock level. In a more complex case, we might use the AIF correlative:

AIF 2=5 THEN "OK" ELSE IF 2<5 THEN "LOW" ELSE "HIGH"

which will further output one of the words HIGH, LOW or OK according to the relative sizes in attributes 2 and 5. On R83 implementations which do not offer AIF, the user must produce these results by exploiting the simple logical operations shown above.

The reports in Figure 1 illustrate how we might perform the logical test:

IF 2 < 5 THEN print 'LOW' ELSE print 'OK'

by means of the A code:

A"OK LOW"[(2<5)*"3"+"1","3"]

returning either of the words OK or LOW, according to the values of attributes 2 and 5. It is worth taking a closer look at the action of the code:

(1) We start with a literal "OK LOW" holding the pieces of text which we wish to display as substrings. Pay particular attention to the fact that this is made up of two substrings "OK " and "LOW" both 3 characters in length.

(2) We first compare attribute 2 with attribute 5:

2<5

returning a value of 1 if attribute 2 is less than attribute 5, or 0 otherwise (if 2 is greater than or equal to 5).

(3) We then multiply the result (1 or 0) by 3 (the length of each substring) to produce a result of either 3 or 0, and then we add 1:

(2<5)*"3"+"1"

to find the starting position of the required substring within the literal string, to produce 4 (if the condition is true) or 1 (if the condition is false).

(4) Finally, starting at this calculated position (1 or 4), we extract 3 characters from the literal string.

"OK LOW"[(2<5)*"3"+"1","3"]

to return either OK (if attribute 2 is greater than or equal to attribute 5) or LOW (if attribute 2 is lower than attribute 5).

The same result could have been produced by longer, but possibly more intelligible form:

A("LOW"["1",(2<5)*"99"]):("OK"["1",(2>=5)*"99"])

If, say, attribute 2 (the actual stock level) were multi-valued and attribute 5 (the minimum stock level) were just a single value, then we should use the form:

2<5R

in each case in order to re-use the single value in attribute 5 with each of attribute 2's multi-values.

Figure 1

LIST STOCK DESCRIPTION QTY MINIMUM LEVEL2

STOCK.. Description.............. QTY MINIMUM... LEVEL

1000 DESK, GREEN-BLUE, ASH 8 30 LOW
2000 SETTEE, YELLOW, OAK 18 30 LOW
3200 SIDEBOARD, NEUTRAL, ASH 15 15 OK
4200 SETTEE, GOLD, ASH 55 30 OK
8763 SIDEBOARD, MAROON, ASH 10 15 LOW
9000 SIDEBOARD, YELLOW, ASH 99 15 OK

SORT STOCK BY-EXP LEVEL2 "LOW" DESCRIPTION QTY MINIMUM LEVEL2

STOCK.. Description.............. QTY MINIMUM... LEVEL

1000 DESK, GREEN-BLUE, ASH 8 30 LOW
2000 SETTEE, YELLOW, OAK 18 30 LOW
4200 SETTEE, GOLD, ASH 10 30 LOW
8763 SIDEBOARD, MAROON, ASH 10 15 LOW
8763 SIDEBOARD, MAROON, ASH 5 15 LOW
8763 SIDEBOARD, MAROON, ASH 0 15 LOW

I use a further - albeit somewhat arcane - application of this same technique to produce reports on a file called ACC.SAVES which records the details of my account-save diskettes. Each item on the file is the name of an account which is (or has been) on my system. A report on the ACC.SAVES file shows the name of the account, the rotation number of the latest account-save diskette, the date when the diskette was produced and an indication of whether or not the account is still on the system. It is this last piece of data, produced by the definition ON/OFF which employs the code:

A"OFFON"[((0(TSYSTEM;X;;1)(T1,1)="D")*"3"+"1"),"3"]

which is illustrated in Figure 2. I leave you to work out exactly how the code checks the entry on the SYSTEM file to see whether or not there is a D-pointer, indicating whether or not each particular account is currently on the system.

Figure 2.

SORT ACC.SAVES PRODUCED LATEST ON/OFF

ACC.SAVES........ Produced............. Latest ON/
disk OFF

ACCESS.TEXT 19:11:53 02 NOV 1992 2 ON
DBASE.TEXT 19:22:51 02 NOV 1992 1 ON
DRILLS 16:48:54 18 JUN 1992 1 OFF
MALCOLM 19:02:56 02 NOV 1992 1 ON
PROGRAMS 19:32:59 02 NOV 1992 1 ON
SB+.DEFN 19:08:26 02 NOV 1992 1 ON
SYSPROG 19:11:53 02 NOV 1992 1 ON
SYS.DEV.TEXT 18:09:17 13 JUL 1992 1 OFF

In such cases, we could pick up a simpler substring, as with:

A"XY"[(2<5)*"1"+"1","1"]

and then use the result (X or Y) to return either of two messages held with item-ids X and Y on a text file:

A("XY"[(2<5)*"1"+"1","1"])(TMESSAGES;X;;1)

This is particularly convenient when if the text of the messages is likely to change.

We can extend the previous reasoning and use an alternative technique to return one of three possible values.

Imagine a situation in which we need to carry of the following tests:

If 2 < 5, then output "LOW"

If 2 = 5, then output "OK"

If 2 > 5, then output "HIGH"

In the solution shown in Figure 3, I have established three definitions, called LOW, OK and HIGH which use processing similar to that of the previous example to return null or a string according to the relative values of attributes 2 and 5. A third definition, LEVEL3, then concatenates the results of the other three definitions. Since two of these will always return null, only the required string will be output.

LOW OK
001 A A
002 2 2
003 LOW OK
004
005
006
007
008 A"LOW"["1",(2<5)*"3"] A"OK"["1",(2=5)*"2"]
009 L L
010 1 1

HIGH LEVEL3
001 A A
002 2 2
003 HIGH LEVEL
004
005
006
007
008 A"HIGH"["1",(2>5)*"4"] AN(LOW):N(OK):N(HIGH)
009 L L
010 1 1

Figure 3

LIST STOCK DESCRIPTION QTY MIN LOW OK HIGH LEVEL3

STOCK. Description............. Qty Min Low OK High Level

1000 DESK, GREEN-BLUE, ASH 8 30 LOW LOW
2000 SETTEE, YELLOW, OAK 18 30 LOW LOW
3200 SIDEBOARD, NEUTRAL, ASH 15 15 OK OK
4200 SETTEE, GOLD, ASH 55 30 HIGH HIGH
8763 SIDEBOARD, MAROON, ASH 10 15 LOW LOW
9000 SIDEBOARD, YELLOW, ASH 99 15 HIGH HIGH

The same result could have been produced by the longer, but possibly clearer form:

A("HIGH"["1",(2>5)*"4"]): ("OK"["1",(2=5)*"2"]): ("LOW"["1",(2<5)*"3"])

or even:

A("STOCK LEVEL HIGH"["1",(2>5)*"99"]): ("STOCK LEVEL AT EVENS POSITION"["1",(2=5)*"99"]): ("!! STOCK LEVEL BELOW MINIMUM !!"["1",(2<5)*"99"])

When any condition is false (and returns a value of 0), we take a substring of length 0 (that is, a null value); when a condition is true (and returns a value of 1), we take a substring of length other than 0. These three substrings are then concatenated to produce the output result.

Like all processing codes, these must, of course, all be written on one attribute of the definition.

There may be a situation where output data is held on any of several possible files. For example, we may have a file of invoic es of which the customer code may identify a USA customer on the USA.CUST file or a British customer on the UK.CUST file, or a customer on the OSEAS.CUST file. We can pick up the customer name from the appropriate file by any of the codes:

A((11(TUSA.CUST;C;;1))(TUK.CUST;C;;1))(TOSEAS.CUST;C;;1) or: TUSA.CUST;C;;1]TUK.CUST;C;;1]TOSEAS.CUST;C;;1 or: F;11;(TUSA.CUST;C;;1);(TUK.CUST;C;;1);(TOSEAS.CUST;C;;1)

Each of these codes will pick up the name in attribute 2 of the USA.CUST file; if there is no such item on USA.CUST then it will go on to pick up the name from UK.CUST; if there is no such item on UK.CUST then we use OSEAS.CUST, and so on.

The action of these codes is fairly self-explanatory: we first translate the original code against USA.CUST and return either the customer's name (if it is on the USA.CUST file) or the original code (if it is not on the USA.FILE, since we use the C subcode in the Tfile code). This result is then used as input data to trans late against UK.CUST; this will return either the input data (the original code or the name from USA.CUST) or the translated name from UK.CUST, and so on. This process can be repeated indefinitely for a number of such files.

The solution assumes that the data returned from any of the files (a customer name, in this particular situation) is not a valid key to any of the later files in the sequence.

Since the A code does not provide a facility for the logical AND and OR operators, this must be achieved by some other means. A little mathematical thought will reveal how we might transform the two values 1 and 1 into 1 (to simulate AND) and the two values 1 and 0 into 1 (to simulate OR). For example, we may use an element such as:

(2<3)*(4>5)

to simulate the condition when attribute 2 is less than attribute 3 AND attribute 4 is greater than attribute 5. This will return a value 1 only when both conditions obtain, otherwise it will return a value of 0. This value can then be used in the manner described above. The element:

((2<3)+(4>5))>"0"

can be used to simulate the condition when attribute 2 is less than attribute 3 OR attribute 4 is greater than attribute 5. This will return a value 1 when either condition is true, otherwise it will return a value of 0.

Constructions of this form are illustrated in Figure 4. The defi nition AND.TEST which uses a A code such as:

A(2>"90")*(5="15")

returns a value of 1 or 0, according to whether or not attribute 2 is greater than 90 and attribute 5 is equal to 15. The definition OR.TEST which uses an A code such as:

A((2>"90")+(5="15"))>"0"

returns a value of 1 or 0, according to whether or not attribute 2 is greater than 90 or attribute 5 is equal to 15.

Figure 4

SORT STOCK *A2 *A5 AND.TEST OR.TEST

STOCK..... *A2....... *A5....... AND OR
TEST TEST

1000 8 30 0 0
2000 18 30 0 0
3200 15 15 0 1
4200 55 30 0 0
8763 10 15 0 1
9000 99 15 1 1

We could then apply these forms in any of the contexts which we introduced earlier. For example:

A("LEVEL < 0"["1",(2<"0")*"99"]): ("LEVEL IN RANGE 0-10"["1",(2>="0")*(2<="10")*"99"]): ("LEVEL IN RANGE 10-20"["1",(2>="10")*(2<="20")*"99"]): ("LEVEL IN RANGE 20-30"["1",(2>="20")*(2<="30")*"99"]): ("LEVEL > 30"["1",(2>="30")*"99"])

I hope that the variety of techniques - and especially the alternative methods - which I have presented in this article might inspire you to pursue A codes and to get Access to do more and more work for you and your organization. Access is always capable of doing just that bit more than you think.
Syntax
Options
Example
Purpose
Related

v/typ

Command v/typ Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP, R83
Category BASIC: Syntax (110)
Description displays the justification specification of the dictionary item being processed by Access. See "attribute-type".
Syntax
Options
Example
Purpose
Related attribute.defining.items
attribute-type

tcl.blkio

Command tcl.blkio Verb: Access/TCL
Applicable release versions: AP/Unix, AP 6.2
Category TCL (746)
Description displays or sets the IO blocking factor, or number of frames read in one disk access during sequential file accesses. The setting is global for the whole system, and can be changed at any time.
The "blkio" command controls how many frames are read in one disk access by processes doing sequential file accesses, like the save or Access processors.

Without any argument, the current setting is displayed. If the mechanism is active, the following message is displayed:

IO blocking factor set to n frames.
indicates that sequential access will read "n" frames at each disk access.

If the mechanism is disabled, the following message is displayed:
IO blocking disabled.
indicates that the IO blocking mechanism is not active, and that frames are read one at a time.

The argument "factor" is the number of frames to be read at each disk access. '1' or 'off' disables the grouping of reads. The maximum number of frames that can be read is 64. See the general description of "blocked IO" for a detailed discussion of the blocked IO mechanism.

The blocking factor can also be set by adding the following statement in the virtual machine configuration file:
blkio n
where 'n' is the blocking factor.

The TCL "buffers" command allows monitoring the effect of blocking IO, by the "Frame faults" counter.
Syntax blkio {[factor|off]} {(option}
Options q Quiet. Do not display anything while setting the blocking factor.
Example
blkio
IO blocking factor set to 2 frames.

   Display the current setting.

blkio 4 (q

   Set the blocking factor to 4 frames, suppressing the message.

blkio off
IO blocking disabled.

   Disable the mechanism.
Purpose
Related general.blocked.io
tcl.buffers

attr.type

Command attr.type Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP
Category BASIC: Syntax (110)
Description displays the justification specification of the dictionary item being processed by Access. See "attribute-type".
Syntax
Options
Example
Purpose
Related tcl.ud

perf

Command perf Definition/General
Applicable release versions: AP/Unix
Category General (155)
Description describes various tips, utilities and performance monitoring tools which allow identifying possible bottlenecks in a given configuration.

Introduction

When performance problems are experienced on a system, it is necessary to distinguish problems due to the Unix environment and problems due to a configuration not adapted to the application.

The reader is assumed to have a fairly good understanding of a Pick environment and some knowledge of Unix.

Overview

Unix related performance problems are usually punctual: at one given time, the system performances degrade noticeably, but overall performance should remain satisfactory. These problems are usually fairly easy to track and to fix.

Configuration problems are more insidious, in that they appear repetitively under some circumstances. The basic principle is to monitor the activity of the system over a long period of time during normal system activity. A series of statistics are taken and stored in a log file for later analysis.

The command to monitor the activity is buffers. The command to display the log file is buffers.g.

Unix Related Bottlenecks

The first elements to look at are the results provided by sar to eliminate configuration problems due to an unexpected Unix activity alongside with the Pick activity. Device related problems may also have very visible effects on the overall performance.

SAR Results

See the section 'System Activity Reporting' in the chapter 'System Administration' in the Installation or User's Guide for more details about sar.

CPU usage:

A well balanced system should have a high percentage (above 80-90%) of user cpu usage. High system mode usage indicates too many process switches, or too many system calls. A non null waiting for IO cpu usage indicates disk bottleneck. If the system cpu usage becomes very high, without high IO activity, this may indicate a device problem (see next section).

Paging activity:

The absolute golden rule is to avoid swapping (paging) during normal operations. To avoid swapping, the physical memory must be increased, or the amount of memory allocated to Pick decreased. Surprisingly, if the system swaps, Pick performances may improve by reducing the amount of memory allocated to Pick in the configuration file. Obviously, there are some lower limits which should not be crossed. The Pick activity monitoring should allow determining how far it is possible to go on that path.

If possible, avoid using costly Unix commands during peak hours (compiling is painful, X-window requires a lot of memory, etc...).

If some significant swapping is taking place, control that the memory allocated to Pick (see the verb what) is not bigger than the total amount of physical memory minus the minimum size of memory required for the Unix Kernel (from 2 megabytes for SCO Unix to 6 megabytes for AIX, depending on the Implementation).

To identify which processes are running, do the following (as 'root'):

ps -edalf | grep R

S UID PID PPID STIME TTY TIME CMD
R root 4719 1 ... 07:08:53 24/0 0:05 ap - 24 tty24
R root 8999 10534 ... 07:58:33 89/0 0:00 ps -edalf
S root 10534 4133 ... 08:58:33 89/0 0:00 grep R
R demo 26242 25467 ... 07:10:03 75/0 0:16 demo

The above example shows an extract of the result. This shows that the process 4719 runs Pick on the PIB 24. The process 26242 is a non Pick process which has used three times as much CPU as the Pick process did. By running this command several times, if some processes show several times, it will be possible to identify processes that may be should not be running during peak hours.

Device Problems

The most common problems with TTYs are due to incorrect cabling. When Unix tries to spawn a process (Pick or Unix) attached to a terminal, the device must be ready. If not, Unix 'waits' a bit and tries again. Worse, a port with a DCD in an unstable state can generate many interrupts, which, in turn, generate 'hang up' signals, creating a very important system load. To identify such problem, do the following (as 'root'):

ps -edalf | grep '?'

S root 4184 9047 ... 09:06:26 89/0 0:00 grep ?
S root 25185 1 ... 07:08:52 ? 0:00 ap - 9 tty9
R root 30571 1 ... 07:08:52 ? 23:45 ap - 19 tty19 printer

This command shows the process attached to terminals the system could not open. In the above example,the second line shows a Pick process (pid=25185), in a sleeping state (S): this process does not consume any CPU. The system could not open the terminal /dev/tty9, but the system abandoned tyring to open it. The third line shows a Pick process (pid=30571), in a running state (R): this terminal does use CPU, as the CPU usage '23:45' shows. The system tried to open the device /dev/tty19, failed, as in the first case, but, probably, the cable is incorrect or hanging loose at the other end, and is generating constant signals.

To fix this situation, the terminal must be connected properly or the associated entry in /etc/inittab turned to off instead of respawn. Unfortunately, it is sometimes very difficult to identify which device is in trouble when the above command does not show it explicitly. Only careful checking of the cables or trying to find which ports which did not start as expected, will allow, by elimination, to find the faulty port.

Identifying Configuration Problems

Statistics

The following elements are monitored by the buffers command:


Name Description

Activ Number of Process activations. Each disk read, keystroke, process wake up after a sleep increments this counter. When the number of frame faults is subtracted from this counter, this gives an idea of the volume of data entry.

Idle Idle time. Not supported on Unix Implementations

Fflt Frame faults. This counts the number of disk reads.

Writes Disk Writes. All writes are normally done by the background flush process to update disk from dirty frames in memory. A high number indicates either a lot of updates, but also may be an insufficient memory allocated for the Pick virtual machine.

Bfail Buffer Search Failures. This counters counts the number of failures to allocate a buffer in memory for a new frame. When non zero, this indicates that the memory is insufficient. This counter should never be non zero.

RqFull Disk Read Queue Full. Not supported on Unix Implementations

WqFull Disk Write Queue Full. This counter counts the number of instances where the flusher cannot keep up with the dirtying of frames. This is an indication that either the write queue is too small for the given configuration (see the section 'Flusher Adjustments' later in this appendix) or that the memory is too small.

DskErr Disk Errors.

Elapsd Elapsed time. This is the time in seconds between two sampling. For internal use only.

DblSrc Double Search. This counts the number of collisions between two or more processes frame faulting on the same frame at the same instant. A non zero counter should be exceptional.

Breuse Buffer Re-Use. This counts the number of instances where a memory buffer has been allocated by one process to read one FID and another process allocated the same buffer to contain another FID. A non zero counter should be exceptional.

Bcolls Batch Contentions/Collisions. This counts the number of collisions between a 'batch' process (i.e., a process which is disk intensive) and an 'interactive' process (i.e., a process which is keyboard input intensive). By default, Pick insures that interactive processes are given priority over batch processes in accessing certain resources. See the section 'Batch Processes' in this appendix for more details.

Sem Semaphores Collisions. This counts the number of collisions between two processes trying to access a systemwide internal table.

Vlocks Virtual Locks Failures. This counts the number of cases when a Pick process tried to assert a virtual lock and failed to acquire it because another process had it.

Blocks FlashBASIC or Pick/BASIC Locks Failures. This counts the number of cases when a Pick process tried to assert a FlashBASIC or Pick/BASIC lock and failed to acquire it because another process had it.

B0reg Buffers with no Virtual Registers attached. These are the buffers not currently attached for immediate reference. At any given time, very few buffers are actually attached. It is therefore normal that this number be almost equal to the total buffers in memory.

B1reg Buffers used by more than one process, but not used by its owner any more. These should be in very small number.

B2reg Buffers used exclusively by their owner. On RISC implementations, this situation allows better performance, because there is no conflict on these buffers. Normally, these buffers contain private workspace, data which is not shared, etc...

B>3reg Buffers used both by their owner and other processes. This number represent the number of pages actually shared among processes (data files) at any given time.

ww Write Required. This counts the number of buffers currently modified and not yet written to disk.

IObusy Buffers being read from disk. This counts the number of pending disk reads. This counters is usually null, since the reads are too fast to be picked up.

Mlock Number of buffers memory locked. If the ABS section is locked, this number is at least equal to the ABS size. Also included, are the tape buffers when the tape is attached.

Ref Referenced Buffers. This counts the number of buffers which have been recently used.

WQ Write Queued. Number of buffers currently enqueued for write.

Tophsh Top of Hash. This number measures the quality of the hashing algorithm used to find a frame in memory. This number must be high (above 60% of the total buffers).

avail Available buffers. Number of buffers candidate for replacement. These are the buffers that nobody has been using recently. When this number drops below 10% of the total buffers, performance decreases significantly.

batch Batch Buffers. This is the Number of buffers used by batch processes. A high level (something approaching 50% of disk buffers) indicates that disk intensive activity is taking place by batch processes.


Activity Log File

The activity log is stored in the file buffers.log with a data level per weekday (buffer.log,Monday, buffer.log,Tuesday, etc... ). The file is created automatically when the buffers (H) command is used for the first time. Each data level is cleared when changing day, so that the file records a whole week of activity automatically. The itemid is the internal time on five digits.

The buffers command also creates automatically the dictionary attributes corresponding to the various counters, as shown in the table above. The attribute TIME displays the sampling time.

The attribute DESCRIPTION in the D pointers Monday, Tuesday etc... contains the date.

The file is created with a DX attribute.

Monitoring Activity

Logon to the dm account. Type:

buffers {(options}

options


C Clear todays log data level, when used with the (H) option. This option must be used the very first time. To restart the monitoring after having stopped it for a while, do not use the (C) option.

H{n} Record statistics in the log file. If followed by a number n, the process sleeps n seconds between each sample. The default value is 5 seconds. When sampling over long periods, 5 minutes (300 seconds) are a good compromise between accuracy and volume of data.

L{n} Loop sampling and displaying statistics. If followed by a number n, the process sleeps n seconds between each sample. The default value is 5 seconds.

S Display system counters. Without this option, a simplified set of counters is displayed. All counters are always recorded, even without this option.


Examples:

buffers

Take one sample of the non-system statistics.

buffers (sh300c

Loop displaying all counters, recording history and sampling every 300 seconds (5mn). The log file data level corresponding to today is cleared, thus starting a new session.

When looping, buffers polls the keyboard to detect the key "x" to stop or "r" to redraw the screen if it has been disturbed by a message, for instance. Any other key forces buffers to take another sample.

Displaying Log File

Raw display

The history file can be displayed by any access sentence. For example:

sort buffers.log,friday with time >= "11:14:00"

Histograms

The buffers.g command lists the log file as a series of histograms. The syntax is:

buffers.g cntr [day{-{day}}|*] {step {strt.time-{end.time}}} {(option}

cntr Statistic counter name (eg. fflt for the 3rd counter). Must be among the list shown in the table above. If the counter specified is relative to the buffers, percentages of the total buffers are displayed, rather than raw figures.

day Day{s} to list. The day can be one day, expressed either explicitly (monday, tuesday, etc...) or a number from 1 (Sunday) to 7 (saturday). A range of days can be specified by specifying two days separated by a dash (-). If the second day is omitted, Saturday is assumed. The whole week can be listed by using an asterisk (*).

step Specifies the display time step as HH:MM{:SS}. All samples taken within the step are accumulated and averaged. If step is not specified or if the step is 0, or if the step is smaller than the sampling period in the log file, all samples are displayed.

strt.time Starting time. If no starting time is specified, 00:00:00 is assumed.

end.time Ending time. If no ending time is specified, 23:59:59 is assumed.


Options


P Direct output to printer.

Examples:

buffers.g fflt * 01:00:00

List the number of frames faults (disk reads), for the whole week, by step of one hour. In the example below, no history was recorded before Wednesday.

No log for Sunday

No log for Monday

No log for Tuesday

20Feb1991; Wednesday; Ctr=fflt, Step=01:00:00, Range=00:00:00-23:59:59

0 8848 17696 26544 35392 44240 53088 61936
+------+------+------+------+------+------+------+------+----
10:59:28 *************************
11:59:54 ***********************************************************
13:00:25 **********************************************************
14:00:52 ************************************
15:01:18 ***************************
16:01:49 ********************************************************
17:02:22 ***************************************
18:02:55 ******
19:03:32 ***********************************************
20:04:08 *************************************************
21:04:43
22:05:21 ***************************************************
23:05:55 *************

Number of samples : 155
Total : 622070
Average per period : 7.1999 / sec.
Max value : 88481
Peak time : 13:00:25

buffers.g ww monday-friday 00:30 08:00-17:30 (p

List the percentage of write required write required buffers, for the week days only, during business hours, by steps of 30 minutes.


Interpreting Results

After taking a significant sample, list the results with the buffers.g command . The most useful parameters to survey are:


Fflt This measures the number of frame faults. If this number approaches the disk bandwidth as determined by the manufacturer, the system becomes disk bound. Solutions range from increasing the memory allocated to Pick, to changing disks, or reorganizing the Pick data base on separate disks to increase parallelism.

Writes This number should stay about one third to a half of the number of frame faults. It is not 'normal' for a system to do more writes than it reads, under normal operation. If this is not the case, see the section 'Flusher Adjustment' in this article.

Bfail This number should never be non zero. If it is not the case, the memory allocated to Pick is definitely too small.

WqFull This number should not be non-zero 'too often'. If it is the case, and if the number of writes is too big also, there is an abnormal rate of writes. See the section 'Flusher Adjustment' in this article.

Bcolls If this number becomes too high, this indicates that a lot of batch jobs (like selects of big files) are done while other processes are doing data entry. It is also an indicator that indeed interactive jobs are receiving higher priority than batch processes. See the section 'Interactive - Batch Processes' below.

ww This number should never go above 50 % of the whole buffer pool. If this is the case, the flusher is probably not activated often enough. See the section 'Flushed Adjustment' below.

avail This number should never go below 10% of the whole buffer pool. If this is the case, memory must be increased or the flusher must be adjusted.


Flusher Adjustment

The flusher is a background process, started automatically at boot time, which scans the Pick memory and writes back to disk frames which have been modified. It is an important task, not only to ensure that data gets back on disk, but also to make room for new data. Usually, a process reads data, modifies it, but may not need it for a 'long' time. The flusher takes care of writing the data back on disk so that the memory can be reused to read in other data.

This 'cleaning' of the memory is done:


- Periodically, when the disk is not active. If the disk becomes inactive 'for some time', the flusher wakes up and scans the memory writing back all it can unless another a process requires a disk access. This period is defined by the flush statement in the configuration file.

- On demand. When the memory gets 'full', i.e., when a lot of pages in memory have to be written back to disk, the flusher wakes up immediately.


The more often the flusher gets awakened, the more often memory is written back to disk. But this creates disk activity, thus decreasing the disk channel bandwidth available for 'useful' work, and CPU activity, therefore adding system load. Another catch to a high frequency flush is that data which is being modified (workspace, select lists, etc...) may be written several times on disk when only the last time would have been necessary.

The verb set-flush allows changing the flush period (see the section 'TCL commands' in this document. Increase this period, checking with buffers that the 'write queue full' events remains low and that the number of available buffers does not drop too low. Normally, the system is self regulating, increasing the flush frequency in case of high memory usage, so there is no need for a low flush period. 30 seconds should be a high limit.

The configuration file also contains the statement dwqnum which defines the length of the internal write queue. Increasing this queue reduces the probability of the situation in which the flusher awakened on critical demand, thus reducing the number of flushes. The down side to increasing the write queue size is that the flusher works by 'bursts', which may overload the disk channel when this phenomenon occurs. This parameter cannot be changed dynamically, which makes a bit more difficult to monitor.

Interactive - Batch Processes

Pick user processes are divided into two classes, depending on the type of activity they have: interactive processes are processes which typically do keyboard inputs 'frequently'; a batch process is a process which has little keyboard activity, require a lot of disk i/o, and/or is CPU intensive.>The system automatically discerns which type of process is running based on internal statistics.

The System Adminstrator can bias and/or override the default parameters used by the prioritization mechanism. Though not recommended, one can even force any processes, regardless its process activity, to be seen by the system as "interactive", for example. This can be changed dynamically on a per process basis via the set-batch command Also, the TCL command set-batchdly allows the displaying and setting of global values used in the queueing of certain types of process activity.
Syntax
Options
Example
Purpose
Related tcl.what
tcl.set-batchdly
tcl.set-batch
tcl.syschk
tcl.buffers
unix.performance

access.sellist

Command access.sellist Definition/Access: Verbs
Applicable release versions: AP, R83
Category Access: Verbs (152)
Description represents the set of selection criteria clauses that determine which items should be selected for processing by Access.

See the "with" modifier for additional information on selection criteria clauses.
Syntax
Options
Example
list entity with name "ar]" name

In this example, only those items whose "name" field begins with 
"ar" are selected. (See "selection criteria" for more 
information).

list entity with name "mi]" and with phone "804]"

This example shows two selection clauses connected with an "and", 
which means that both conditions must be evaluated as true for items to be 
selected for processing.

list entity with name "re]" or with city "irv]" name city

This example shows a mutually exclusive set of selection crtieria connected 
with an "or". Either condition evaluating to true accepts the item 
for processing, that is, if the "name" attribute begins with 
"ar", or the "city" attribute begins with "irv", 
the item is selected for output.

list entity with name "ar]" and with city "irv]" or with 
city "san]" and with contact "[joe]"

This example lists those items which meet one of two criteria: a name starting 
with "ar" and with a city starting with "irv", or, a city 
starting with "san" and a contact containing the string 
"joe".
Purpose
Related access.select
access.without
access.t-dump
access.selection.processor
access.sselect
tcl.sortc
access.sreformat
access.sort
access.t-load
access.with
access.s-dump
access.sum
access.nselect
wildcards
access.sort-label
access.stat
tcl.ld
access.list-label
access.count
access.list-item
access.list
access.verbs
collation.order
access.logical.connectives
access.or
access.and

sdb

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

The Monitor Debugger allows:

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

IMPORTANT

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

Entering the Debugger

The debugger can be entered:

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

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

CONDITION MESSAGE PROMPT

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

Referencing Data

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

Data Specifications

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

The data is always displayed in hexadecimal.

Virtual Address Specification

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

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

For example:


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


Monitor Address Specification

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

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

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

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

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

For example:

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


Window Specification

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

Changing Data

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


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

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

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


Debugger Commands

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


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

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

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

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

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

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

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

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

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

bl List break points. List the Monitor break points.

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

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

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

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

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

b : Dump the buffer table.

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

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

g : Dump the global space.

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

p : Dump the pibs.

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

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

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

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

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

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

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

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

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

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

nncf:frmn:frmp:npcf:clnk=

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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


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


Usage Hints

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


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

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

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

To restart the multiuser activity:

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

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

All processes will now be unlocked.

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

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

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

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


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


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


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


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


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


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


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

Precautions

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

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

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

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

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

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

tcl.set-ovf-local

Command tcl.set-ovf-local Verb: Access/TCL
Applicable release versions: AP 6.1
Category TCL (746)
Description sets and displays the local overflow cache size. The presence of a local overflow cache enhances both performance and reliability, and is automatically set up to a reasonable default by the system. Users who wish to further tune their overflow usage may use the "set-ovf-local" command to change this cache to tailor it to specific needs.

When given without any options, the "set-ovf-local" command displays the cache status for the current line. The display shows a 2 by 2 grid of numbers. The explanation for these is as follows:

Legend: (see examples)

"Current" is the current number of frames actually held in a given cache.

"Max" is the maximum number of frames that the cache may hold. Any overflow released to the cache when it has reached its maximum size will be deposited directly into the main overflow table.

"WS" is the row showing the current and maximum workspace cache sizes.

"File" is the row showing the current and maximum file cache sizes.

Parameters:

Besides displaying the current cache status, "set-ovf-local" can be used to modify the current cache maximums by specifying the following numeric parameters on the command line:

ws.max This sets the maximum workspace cache size.

fs.max This sets the maximum filespace cache size.

Cache descriptions:

The workspace cache is a generalized cache used for virtually all memory needs. It is automatically set to a default so that simple TCL commands and FlashBASIC and Pick/BASIC programs will not need to access the global overflow table and can thus avoid the performance cost of doing so. If the user is repeatedly using EXECUTE's of more complex programs, then he/she can try boosting the workspace cache size to see if performance improves.

The file cache is used only when update-protection is active. The update-protection scheme deposits frames into this buffer which it guarentees are syncronized so that no other file or workspace on the disk points to it. This virtually eliminates the posibility of so-called "doubly linked frame" where two files are attached to the same frame after a power outage or crash. This cache is should be large enough to cover the largest group or largest pointer item that is protected by the update protection scheme. For example, if the user has a file with 30K byte items on a 2K frame system, then the file cache should be set to at least 30K/2K = 15 frames.

Cache tuning:

Ideally, a system should be able to operate out of private overflow caches as much as possible. The less the system accesses the global overflow pool, the greater the system performance, and the less chance there is for the overflow to become corrupted in the event of a power outage. To tune the cache sizes, users can try different cache settings, and run the "buffers (s" program to see the change on overflow access. The fields "WS OVF locks" and "FILE OVF locks" show the number of references to the global overflow table per second.
Syntax set-ovf-local {ws.max}{, fs.max} {(options}
Options s supresses the display.

f flushes all caches. All frames held within the current cache are released back to the main table. Note that this operation is automatically invoked when the maximum values are changed. The act of logging off the system will automatically flush all local overflow caches.

g Copies the current maximum cache settings into the global default. Whenever a new user logs in, he/she will automatically aquire this default value. Note that the global defaults are automatically preset to a factory specified value upon reboot, so if a permanent global change is desired, the user should place the "set-ovf-local" command in the system-coldstart macro.
Example
set-ovf-local
        
Private Overflow Cache Status:
            
           Current   Max
                   
WS            2      20
File         10      30

This shows that there are currently 2 workspace frames in the overflow cache 
with a maximum capacity of 20 frames, and 10 file space frames in the overflow 
cache with maximum capacity of 30 frames.

set-ovf-local 100,300 (s

This command will set the maximum workspace cache size for the current line to 
100, and the maximum file space cache size to 300.

set-ovf-local (fs

This command releases all frames in the current overflow cache to the global 
pool.

set-ovf-local 100,300 (sg

This command will set the maximum workspace cache size for the current line to 
100, and the maximum file space cache size to 300.  The settings will also be 
copied into the global default area.  All users logging into the system after 
this command has been executed will automatically get caches sized to this 
specification.
Purpose
Related tcl.init-ovf
tcl.rebuild-ovf
tcl.set-runaway-limit
tcl.set-ovf-reserve
pointer.item

justification

Command justification Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP
Category BASIC: Syntax (110)
Description displays the justification specification of the dictionary item being processed by Access. See "attribute-type".
Syntax
Options
Example
Purpose
Related at

compile.time.date.stamp.rp

Command compile.time.date.stamp.rp Definition/BASIC Program
Applicable release versions: R83
Category BASIC Program (486)
Description defines the structure of Pick/BASIC object pointers.

When a program is compiled in an R83 release, a pointer is placed in the dictionary level of the file in which the source program resides. This pointer defines where the object code resides and is used whenever the program is run. The structure of the pointer is as follows:

Attr Contents Description

0 item-id Same as the source item.
1 CC Literal "CC".
2 fid "Base" fid of object code.
3 frames Integer number of frames used.
4 nothing
5 time/date The time/date of the compile.

The actual format of the time date is as follows:

hh:mm:ss dd mmm yyyy

The date begins in the eleventh character position, for a length of eleven characters. An attribute-defining item can be placed into the md of the account to obtain the actual compile date, in a form where it can be used by Access, even though it is stored in "external" format. This ADI would appear as follows:


Attr Contents

0 item-id (for our example, assume "PF.DATE")
1 A
2 5
3
4
5
6
7 D2/
8 T11,11]DI (Note that "]" is a value mark)
9 R
10 8

With this item in place, it is now possible to produce a report with Access. See the examples below.
Syntax
Options
Example
SORT DICT BP BY-DSND PF.DATE PF.DATE

This produces a report in which the  most recently compiled programs sort to 
the TOP of the list. This is useful for  length   determining if a particular 
program compiled successfully.

SORT DICT BP WITH NO PF.DATE

This report only affects those items which have NOT been compiled.
Purpose
Related compile.time.date.stamp.ap
tcl.basic
tcl.compile
tcl.run
tcl.pverify
r83.source.files
value.mark
pc.d
pc.text.extract
attribute.defining.items

system.security.article

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CALLX PROGRAM

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

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

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

pc.d

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

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

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

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

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

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

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

The following formats can be used to input dates:

Format Description

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

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

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

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

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

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

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

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

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

m Numeric month (1-12).

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

q Numeric quarter (1-4).

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

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

y Year (default is 4 digits).

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

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

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

system.debugger.dfs

Command system.debugger.dfs Definition/System Debugger
Applicable release versions: AP, R83, AP 6.1
Category System Debugger (42)
Description specifies the output display format mode of operation to use.

It precedes the address of the data to access. Once set, the "data.format.specification" remains in the designated mode until explicitly changed and is applied to subsequent data displays which do not specify a different data format.

The "data format specification" is one of the three elements used in referencing disk locations within the system debugger; it specifies the output format: either "integer", "character" (ASCII) or hexadecimal.

The data format specification is optional. If unspecified, the previous format specification is used for the current data display. If no format has been assigned, hexadecimal format is the default.

All of the following are invalid with the use of the "a" or the "l" commands, and will generate error messages.

"data.format.specification" options:

c Character format.

i Integer format. The maximum window specification is 6. Larger numbers give unpredictable results.

x Hexadecimal format.

w Hexadecimal Word format. This is identical to the "x" format, but data is displayed in 2-byte words meaning that the output will be un-byte-swapped on Intel platforms. Available on 6.1.0 and above only.
Syntax
Options
Example
!x/mbase<return>     <- Enter this.
!x/mbase .00017A5B=  <- This displays.

!c/mbase<return>     <- Enter this.
!c/mbase ...[=       <- This displays.

!i/mbase<return>     <- Enter this.
!i/mbase 108379 =    <- This displays.
Purpose
Related system.debugger.dws
system.debugger.r
system.debugger.functions
system.debugger.overview
system.debugger.drs
system.debugger.x
system.debugger.a
system.debugger.c
system.debugger.i
system.debugger.l
system.debugger.w

access.introduction

Command access.introduction Introductory/Access: Verbs
Applicable release versions: AP, R83
Category Access: Verbs (152)
Description a Pick facility to retrieve and output data.

Access is an original piece of the Pick System and is made up of the List pre-processor (the oldest), the Select processor, and the Output processor.

Access is a system-level information retrieval language that allows users to query their data base without writing complex programs.

Access uses TCL commands as verbs and displays the results either on terminals or printers. An Access verb operates on specified files and items based on various 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 the most accessible data management system in existence.

Additional Advanced Pick features enhance the already comprehensive query language. Pick/BASIC and FlashBASIC calls from dictionaries are used for complex data calculations and output formatting. The "ss" (spread sheet) connective allows printing 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.

Use of b-tree indexes has increased the speed and performance of Access. See "b-tree" in see.also.

Access commands are entered at TCL and thus can be recalled, modified, or executed through utilization of the TCL-stack. Access sentences may also be stored and invoked through macros, menus, procs, FlashBASIC and Pick/BASIC (using the "execute" statement).

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 a TCL 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 may be used with any of the elements of Access sentences to allow exact specification of the conditions to be met.

"file.reference" is the name of a file in the "md" to which the user is currently logged. It can also be a synonym file name, or "q-pointer". 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 or q-pointers may be 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 four following forms:

account.name,dict.name,file.name
account.name,file.name,
dict.name,file.name
file.name

"account.name,dict.name,file.name" is the fully qualified form, specifying all elements of the path.

"account.name,file.name," defaults the dict.name to the same as the file.name.

"dict.name,file.name" defaults the account.name to the current account.

"file.name" defaults the account.name to the current account and the dict.name to the same as the file.name.

The following form references a master dictionary, defaulting to: mds,account.name: account.name,,

Commands requesting a destination or source with a "to:" or "from:" prompt, such as "copy" and <ctrl>+cp (cut and paste from a specified item), expects an item-id (or itemlist), or a file.reference, or a file.reference and item-id. To name a path or file, the file.reference must be preceded by a parenthesis.

"itemlist" specifies one, some, or all 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 list is not active, a null item-id implies a new item for UP and all items for the other processors. To cause a processor to use the active 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.

An active list can be used by another "select" statement to narrow down the resulting list. A list can be passed to another list until a "save-list" or any other Access, TCL2, or Pick/BASIC verb is invoked. For example:

select entity with state = "ny"

n items selected.
select entity with city = "syracuse"

m items selected.
list entity name city state phone

The above series of statements first selects all entites in the state on new york, and out of these selects all entites in syracuse and then outputs a columnar report.

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

The item-id is always displayed unless it is suppressed using the "id-supp" connective or unless it is suppressed using the "i" option on the output-macro attribute of the associated file-defining item (AP only).

"print limiters" suppress the listing of attributes within an item that do not meet specified limits.

"modifiers" control listing parameters such as double-spacing ("dbl-spc"), control breaks ("roll-on" or "break-on"), column totals ("total"), and suppression of item-ids ("id-supp"), automatic headings ("hdr-supp" or "col-hdr-supp"), and default messages ("ni-supp").

"(options)" are 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.

Command results are reported to the terminal unless the "p" option is used to direct output to the Spooler. They are usually preceded by a left parenthesis, except in the case of spooler options. At this time, the right parenthesis is optional at the end of the option specification. When used, options must be the last element on the command line. See the "see.also" attribute for a listing of Access verbs.

On 6.1 releases and above, tabbed output is possible by modifying the master dictionary item. See the "tabbed.output" token for more information.
Syntax
Options
Example
Purpose
Related access.verbs
access.selection.criteria
access.count
access.list-item
access.list
flash.basic.differences
collation.order
up.options.s
access.ss
b-tree
basic.execute
access.itemlist
file.reference
access.itemlist
access.modifiers
access.options
list.processor
access.pre-processor
access.any
ue.1209
access.tabbed.output
up.macro

at

Command at Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP
Category BASIC: Syntax (110)
Description displays the justification specification of the dictionary item being processed by Access. See "attribute-type".
Syntax
Options
Example
Purpose
Related attribute-type
justification
frame

general.blocked.io

Command general.blocked.io Definition/General
Applicable release versions: AP/Unix, AP 6.2
Category General (155)
Description describes the mechanism by which a Pick process does blocked IO, in order to improve disk performance.
Processes doing sequential disk accesses, like the file save, or Access statements, have the possibility of grouping several disk reads into one larger disk access. This has the advantage of reducing the number of disk accesses and, therefore, improve performance. For example, selecting a 10,000 frame file normally requires 10,000 disk accesses. If the process can read four frames at a time, it will do only 2,500 disk accesses. Even if reading 4 frames (8 kilobytes on a 2 K frame system) takes a little bit longer than reading only 1 frame (2 kilobytes), reducing the number of disk accesses usually results in a noticeable performance improvement.

The cost of using blocked IO is a greater memory demand on the system, and might have some impact on multiuser performance.

The net effect of grouping the disk reads is reducing the number of 'frame faults' (i.e., when a Pick process requires a page which is not currently in memory). This can be monitored by the TCL command "buffers".

The blocking factor (or number of frames read in one disk access) can be set by the TCL command "blkio" for the whole system, or as an argument in the configuration file.
Syntax
Options
Example
Purpose
Related tcl.blkio
tcl.buffers

access.c/bytes

Command access.c/bytes Attribute Defining Item/BASIC: Syntax
Applicable release versions: AP 6.1
Category BASIC: Syntax (110)
Description displays attribute 11 of compiled binary items through the list-obj TCL command. This is the number of bytes of Pick object code. It is also available to Access.

This attribute holds the number of bytes of the actual compiled object code within the frame(s) that hold the binary item. This information is useful to estimate the number of frames that will be necessary to FlashBASIC compile standard Pick object code. This is typically 4 times the size in bytes, but is dependent on implementation, optimization level and related options, like "f".

This byte count does not include the symbol table, FlashBASIC code or the size of the compile date-time stamp.
Syntax
Options
Example
list dict bp c/bytes

Page   1     DICT bp

DICT bp........ bytes..

test            234
test2           439
Purpose
Related tcl.compile
compile.time.date.stamp.ap
tcl.list-obj

up

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

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

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

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


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

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

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


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


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


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

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


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


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

Overloaded UP Commands for Data Files
Most UP commands work the same whether or not dictionary attributes are in control. Certain commands function differently when certain conditions are met. These commands provide the functionality for browsing on indexes. The cruising commands can be used in a double-clutching fashion by specifying the index for the current file and a second index for another file. <Ctrl>+u and <Ctrl>+y cruise on legal instances in the pointed to file staying in the same item. <Ctrl>+f and <Ctrl>+d cruise on other items in the same file using the index for the attribute as a guide.
<Ctrl> +
g When in an attribute which indexes to another file or has a translate code in the input processing code, this command pushes the current process one level and calls UP again with the item pointed to in the new file as the argument. If the macro attribute (attribute 15) in the primary file attribute definition item is used, this list is appended to the update statement. This is known as "zooming".
f On an indexed attribute, the sentence forward command goes to the next sequential index and gets the corresponding item into the UP workspace.
d On an attribute with an index, the sentence backward command goes to the previous sequential index and gets the corresponding item into the UP workspace.
u If the attribute indexes to another file, the word forward command gets the next sequential item from the pointed to file as the value for this attribute.
y If the attribute indexes to another file, the word backward command gets the previous sequential item from the pointed to file as the value for this attribute.
Syntax
Options
Example
Purpose
Related up.a
up.sc.a
up.sc.aa
up.sc.aaa
up.arm
up.arn
up.b
up.c
up.options.c
up.cc
up.cd
up.cl
tcl.compile-run
up.correlative
up.correlative.adi
up.cp
up.cr
cruising
up.cut.paste
up.cw
up.d
up.data-entry
up.delete.text
double.clutching
up.e
up.exit.item
up.f
up.g
up.h
hotkeys
up.i
up.options.i
access.id-prompt
up.input-conversion.adi
up.input-conversion.fdi
up.insert.mode
up.j
up.k
up.l
up.options.l
up.m
up.n
up.o
up.only
up.options
up.output-conversion.adi
up.overtype.mode
up.p
up.prestore
processing.codes
up.r
up.options.s
up.search.replace
tcl.spelling.checker
up.t
up.u
up.commands
update.processor
up.v
up.w
up.x
up.x0
up.x1
up.x2
up.x3
up.x4
up.x5
up.x6
up.x7
up.x8
up.x9
up.xb
up.xc
up.xe
up.xf
up.xi
up.xk
up.xl
up.xn
up.xo
up.xp
up.xr
up.xs
up.xx
up.y
up.z
up.znumber
up.za
up.zb
up.zc
up.zd
up.ze
up.zg
up.zh
up.zl
up.zn
up.zo
zooming
up.zp
up.zq
up.zr
up.zs
up.zt
up.zw
up.zy
up.zz
up.zx
up.macro
updte.processor

basic.access

Command basic.access Function/BASIC Program
Applicable release versions: AP, AP 6.1, AP 6.2
Category BASIC Program (486)
Description provides data about the Access or UP environment when the program is called from a dictionary.

Access() can only be used in subroutines that are called from a dictionary item when in Access or UP and allows information about the controlling environment to be read and altered by the subroutine.

The following list represents the valid numeric expressions which may be specified in the "access()" function:

1 file.variable for data portion of file.

2 file.variable for dictionary portion of file.

3 Item from the associated file in dynamic array format. If the item is new, this contains "" (null).

4 Item counter (the number of items processed to the current point).

5 Attribute counter (the number of attributes processed).

6 Value counter (the number of values processed).

7 Subvalue counter (the number of subvalues processed).

8 Detail line counter (the number of lines processed).

9 Break-on level counter

10 Item-id.

11 File name.

12 Item delete bit. Returns 1 if the item is being deleted.

13 Root variable.

14 Returns current cursor column position (in UP).

15 Returns current cursor row position (in UP).

16 New item bit. Returns 1 if item is new.

17 Returns 1 if doing input-conversion.

18 Used in the input-conversion attribute of the file "d-pointer" to specify which value of attribute 15 ("macro" attribute) to use.

19 Returns the character which ended the last input, usually a <return>, <ctrl>+u, etc.

20 Item changed bit (0-item not changed, 1-item changed). This is valid only when called from the Update-Processor using a call correlative.

21 This is used from a Pick/BASIC subroutine called by UP to place characters in the UP command string. For example, access(21) = "xe" in a subroutine called from the input-conversion causes the Update processor to exit after the attribute calling the subroutine is re-entered.

22 Returns a non-zero (usually 1) if the spelling checker is enabled, or 0 if it is not. Access(22) may be assigned a "1" in a subroutine called by the input conversion of a file-defining item. Even if the spelling checker is disabled for the user session, this invokes the speller for the editing of this item or list of items. The speller will only on attributes with an attribute type of "w". See "attribute-type". Access(22) is available in AP releases 5.2.5 and 6.0.0 and higher only.

23 Returns the calling environment. It returns 0 if the function was called from FlashBASIC or Pick/BASIC, 1 if the function was called from a callx or from an index, 2 if the function was called from the Update processor (except for a callx or index), and 3 if the function was called from Access. Access(23) is available in AP releases 6.1.0 and higher only.

24 Returns the actual attribute number of the attribute definition. Available on 6.1.0 and higher only.

25 Returns the left margin from the Update processor (6.2 and above).

The access(3) and access(10) functions can be used to pass data both ways between a Pick/BASIC program and a data file.

When either of these two statements appear on the right of the assignment (= sign), data is passed to the program. When they are used to the left of the assignment, data is passed from the program to the file.

access(3) can be updated only from an input-conversion of a dictionary item. It cannot be updated as a conversion, correlative or in a "d-pointer" input-conversion.

The item-ids as well as the remainder of the attribute values within those items can be modified directly through the UP using input conversion or correlative attributes in dictionary items.
Syntax access(num.expression)
Options
Example
The following program is called from a "hot" key in the Update 
processor.  It gets the current file name from access(11) and executes a 
special "help" processor. The "access(21)" macro return 
function is set to <ctrl>+z and p which rediplays the current screen.

subroutine do.help(item)
file.name = access(11)
tcl "help ":file.name
access(21)= "z'p'"
return

This example works as well for Update as it does for Access to extract the last 
element of a value list. (Or subvalue for that matter). The date stamp is 
attribute 11 of the item. "max" is the total number of multi-valued 
elements on the stamp.  If "max" is zero, there is no stamp. If max 
is non-zero, the last value is extracted and placed into the active data value, 
"fld".

subroutine get.last.date.stamp(fld)
date.stamp = access(3)<11>
max = dcount(date.stamp,char(253))
if max = 0 then return
fld = access(3)<11,max>
return
Purpose
Related basic.statements
pc.call
file.defining.items
basic.subroutine
pc.callx
basic.functions
tcl.speller
tcl.speller-off
tcl.speller-on
tcl.spelling.checker
up.sc.a
filename.words
up.sc.aa
up.sc.aaa
up.input-conversion.fdi

access.^

Command access.^ Modifier/Access: Verbs
Applicable release versions:
Category Access: Verbs (152)
Description
Syntax
Options
Example
Purpose
Related wildcards