ap.dict.sub.calls Article/Article, up.co Command/Update Processor

ap.dict.sub.calls

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Figure A

customer 'customer'

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

Figure B
DICT customer

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

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

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

update customer

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

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

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

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

date
name
phone.number
type
terms

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

name
phone.number

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

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

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

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

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

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

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

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

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

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

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

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

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

up.co

Command up.co Command/Update Processor
Applicable release versions: AP
Category Update Processor (113)
Description copies the entire contents of the current value into the cut buffer. This is mostly used in attributes with conversions.

The "<ctrl>+cp" command inserts the current contents of the cut buffer at the current screen coordinate. The cut buffer remains intact until the Update processor is exited or another cut is performed.
Syntax <ctrl>+co
Options
Example
Purpose
Related up.c
up.cut.paste
up.cp
cut.paste
up.ci