Applicable release versions: AP
|Description||using the "call" statement from dictionaries.
Contributed by Terri Hale
(original article ran in PickWorld Magazine)
This article will show the reader how to call a subroutine from the file-defining item (aka "d-pointer") and the attribute-defining item. It will also explain when the calls take place. Emphasis will be placed on the special relationship that exists between the Update processor (UP) and the new "access" function in Pick/BASIC.
With a Pick/BASIC subroutine call from a dictionary, the access function allows the subroutine to interrogate and/or modify data from the calling environment. This means that the Update processor can pass data as well as other specifications pertinent to the calling environment to a subroutine. The subroutine can then perform any action required, including modifying the data, before returning control of the item to the Update processor.
See the "access (Pick/BASIC: Function)" for a complete list of the expressions available with the access function.
Pick/BASIC subroutine calls from the file-defining item:
From the file-defining item, subroutines can be called from the correlative and input-conversion dictionaries.
CORRELATIVE call file.time.subroutine
INPUT-CONVERSION call before.update.subroutine
Note that the syntax for calling a subroutine does not specify any parameters. However, when a subroutine is called from the file-defining item, the entire item body is passed as a parameter.
When a subroutine is called from input-conversion of the file-defining item, control passes to the subroutine before the operator gets into the file via the Update processor. That is, after the UP command has been executed (:u filename) and before the user can get access to the item. This is where access(18) can be assigned a value determining which "view" of data UP dis plays.
When a subroutine is called from the correlative field of the file-defining item, control passes to the subroutine at file time. In other words, when the item is filed by UP, the subroutine is called. The entire item body is passed to the subroutine. Any wrap up file time processing could be done here.
Pick/BASIC subroutine calls from the Attribute-Defining Item:
From Attribute-Defining Items, Pick/BASIC subroutines can be called from output-conversion, correlative, and input-conversion.
OUTPUT-CONVERSION call output.subroutine
CORRELATIVE call preprocessing.subroutine
INPUT-CONVERSION call after.input.subroutine
Subroutines called from OUTPUT-CONVERSION are executed on output. Subroutines called from the CORRELATIVE are executed prior to processing. Subroutines called from INPUT-CONVERSION are executed after input.
Let's look at an example of a "customer" file which calls several Pick/BASIC subroutines from both the file-defining item (see Figure A) and the attribute-defining items (see Figure B).
CORRELATIVE call cust.update
INPUT-CONVERSION call cust.setup
MACRO date name phone.number type terms name phone.number
ac attr-name ty cw input-conversion correlative out-conv
file customer L 10 call cust.setup call cust.update
1 date r 8 d2/ d
2 name l 25
3 phone.number l 15 call phone
4 type l 15 call get.terms
5 terms l 15
To demonstrate the interaction of UP with Pick/BASIC, we will step through the UP command:
The first thing that happens after the operator hits return, is that the subroutine "cust.setup" is executed:
item = access(3)
if access(16) then ; * check if this
* is a new item
item<1> = date() ; * put todays date in
* attribute 1 on new
if system(29) then
user.format = 3
user.format = 2
if user = "th" then
access(18) = 1 ;* Update processor uses
* macro value = 1
access(18) = 2 ;* Update processor uses
* macro value = 2
return ;* return to Update processor
This program puts the system date in attribute 1 if the item being edited is new (using access(16)). It will then decide which "view" of the attributes to be used for updating, depending on who the user logged on happens to be. system(29) returns a '1' if the 'who' command is in R83 format. In AP, the format of the 'who' verb returns port#, user id, master dictionary.)
If the user 'th' is logged on, the Update processor will display the attributes:
For all other users, UP will display the following attributes:
For our example, let's assume that the user is "th". The operator then enters the name and phone.number. On output, the subroutine "phone" is executed.
item = access(3)
value = item<3>
if value then
if value matches "10n" then
formatted.phone.number = oconv(value,"mr(#3/#3-#4)")
inputerr 'Enter phone number with area code and no characters. '
item = ''
This program validates the phone number that was typed in. If entered in error, the subroutine will return control to UP, along with an error message. Otherwise, the phone number will be formatted on output.
Next, the operator types in the "type". The "type" is validated by the sub routine "get.terms". This program also puts a value in the "terms" attribute.
if access(16) then
item = access(3)
if type matches 'n' or type matches 'p' or type matches 'c' then
case type = 'n'
term = "net 30"
case type = 'p'
term = "prepay"
case type = 'c'
term = "cod"
case 1 ; term = ""
item<5> = term
access(3) = item
inputerr 'Invalid type, must be n, p, or c. Please re-enter. '
item = ''
Note that access(3) can be on either side of the equal "=" sign. Access(3) can ONLY be on the left side of the "=" sign when called from input-conversion. When access(3) is on the left of the equal sign, data is passed from the program to the file. When access(3) is on the right side of the equal sign, data is passed from the file to the program.
Now that all the fields have been entered, let's see what the screen looks like:
customer NEW ITEM size 10
date 27 Jul 1991
name Pat Hale
terms net 30
Next, the item is filed. When the item is filed, the subroutine "cust.update" is called.
last.up.command = access(19)
if last.up.command = 'n' then return
if access(12) then
inputerr 'You cannot delete items from this file!'
equate vm to char(253)
if dcount(item<1>,vm) > 1 then
inputerr 'Multi-valued names are not allowed '
This routine will return to UP if the operator is requesting a new item. It will then check of the operator is deleting a customer. If so, he/she will be put back into UP and told that customers can not be deleted. The subroutine will then check to see if more than one name was entered in the "name" at tribute. If so, an error message will print and they will be put back in UP. If there were no errors, then the item will be filed.
|Command||up.c Command/Update Processor
Applicable release versions: AP
|Category||Update Processor (113)|
|Description||moves or copies data from one place to another. The data may reside in the current item being edited, or another item in the current file, or an item in a different file.
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 text in the cut buffer can be pasted into the current item or it can be pasted into a specified item in another file.
Marking the beginning cut location:
There are two ways to mark the beginning position of text to cut. In both commands, the beginning cut position is determined by the position of the cursor when the command is issued.
1) "<ctrl>+cl" marks the beginning position of text to cut and specifies that the text is to be left in place (copied, not moved).
2) "<ctrl>+cd" marks the beginning position of text to cut and specifies that the text is to be deleted (moved) from its current location after it is cut.
UP marks the beginning of the cut with a backslash ("") on the terminal.
"<ctrl>+zz" cancels the beginning cut mark.
Marking the ending cut location:
"<ctrl>+cc" marks the ending position of the cut.
The ending cut position is determined by the position of the cursor when the command "<ctrl>+cc" is issued.
Once the ending position has been marked (UP does not display any character for the end mark.), the marked text is placed in the cut buffer.
As of 6.1, the entire contents of a value can be saved into the cut buffer with one command. To store the internal contents (the value stored in the item), <ctrl>+ci can be used. To store the external contents (the value displayed on the screen), use <ctrl>+co.
Saving the cut buffer:
The "<ctrl>+cw" command writes the contents of the cut buffer to the item specified.
"<ctrl>+cw" causes the Update processor to prompt with:
This prompt appears at the top left corner of the terminal. Enter either an "item-id" or a "file.reference" and "item-id".
If only an "item-id" is entered, the cut buffer contents are saved in the current file. If the file already has an item with the specified "item-id", the following prompt displays at the top left corner of the screen :
'cut.id' item exists on file, press "y" to overwrite:
If any key other than "y" is typed, the cut text is NOT saved. If "y" is typed, the item that was on file is overwritten with the cut item.
If the response to the prompt for cut save-id is a "file.reference" and "item-id", the item is written to the designated file with the specified "item-id". A left parenthesis character is required immediately before the "file.reference" and indicates that a different file is being specified.
Pasting from an existing item:
The "<ctrl>+cr" command reads the contents of the specified item and pastes the contents at the current cursor location.
After "<ctrl>+cr" is entered, the terminal prompts with:
Any valid "file.reference" and "item-id" are allowed in response to this prompt.
When using UP as a text editor, a range of attribute numbers (separated by a space) may be specified after the "item-id". If the beginning and ending attribute numbers are omitted, the entire item is copied into the item being updated at the current cursor location.
When in data entry mode, with dictionaries defining the attributes, "<ctrl>+cr" has two actions, depending on the status of the item being updated. In both cases, the range is omitted.
1) If the item being updated is new and if the cursor is on the first attribute in the item, "<ctrl>+cr" merges the entire item from the source item specified.
2) In all other cases, when "<ctrl>+cr" is entered, the corresponding (same attribute position) attribute is merged into the current item from the source item specified.
Pasting cut at cursor location:
"<ctrl>+cp" inserts the contents of the cut buffer, beginning at the current cursor position.