r83.to.ap.2 Article/Article, basic.file Statement/BASIC Program


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

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

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

Porting Your Programs and Data

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

Saving Your Current Pick Data

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

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

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

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

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

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

Data Exchange Media

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

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

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

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

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

* Serial Data Communications Ports.

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

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

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

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

Loading Your Data to AP

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

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

Setting the restore device

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

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

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

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

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

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

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

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

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


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

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

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

Other Files You Need to Restore or Create

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

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

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

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

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

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

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

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

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

* 'SYSPROG USER-COLDSTART' to 'dm > users' The 'users' file is a file of user.id's, so each user may have their own separate logon procedure. Or, if you want, all the separate user.ids may each call the same macro to set up their environment. Here is a sample user.id :

: list users donna
name Donna Davis
address 1691 Browning Ave.
zip 92714
phone 714-261-7425 714-250-8187 fax
phone.id dd
keys admin sales
password FFA08438
privilege sys2
options n
macro run bp choose.term
set-sym gsym
logto admin

* 'SYSPROG' procs to 'dm' Since you will not be restoring the SYSPROG account, you need to save all of your R83 procs. A typical way to do this is to save them (on the R83 system) to a T-DUMP: : SSELECT MD WITH A1 = "PQ" : T-DUMP MD * And then you may easily restore them (to the AP system) with a t-load: : t-load md * Warning: There may be procs with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a proc because it had the same name as an existing proc. If you do a 't- load (o)', then you run the risk of overwriting a crucial Pick-supplied proc. You may wish to restore them one by one.

* 'SYSPROG BP' to 'dm > bp' In addition, you may have Pick/BASIC programs residing in SYSPROG's 'bp' file which need to be moved over. Again, you can use the T-DUMP / t-load method to restore the programs. Warning: There may be programs with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a program because it had the same name as an existing program. If you do a 't-load (o)', then you run the risk of overwriting a crucial Pick-supplied program. You may wish to restore them one by one.

* 'SYSPROG CURSOR' to 'dm > devices' The 'devices' file contains the output control commands for output devices, namely, terminals and printers. This lets the Output processor change fonts and display styles. The 'devices' file already contains items for many of the popular terminals and printers, so all you probably have to do is to insure that your terminal and printer devices are listed. However, you may have specific terminal defini tion items in your 'SYSPROG CURSOR' file which may not be in Advanced Pick's 'dm > devices' file. If so, you can resort to using the T-DUMP / t-load method to restore them. Warning: There may be definitions with conflicting names. If you do a plain 't-load', then you run the risk of leaving out a terminal definition because it had the same name as an existing one. If you do a 't-load (o)', then you run the risk of overwriting a crucial Pick-supplied terminal definition. You may wish to restore them one by one. If your device is not listed among the entries, then you will have to choose a suitable substitute from the available choices, or create a new entry. For terminals, use the familiar define-terminal program to create a new terminal device. For printers, also use the define-terminal program to create a new printer device. * In addition, there may be some files residing in the 'SYSTEM' dictionary which you will need. If so, then T-DUMP them as well.

Compiling Pick/BASIC Programs

After you have restored all your data onto the AP system, you will have to recompile your Pick/BASIC programs. A typical command would be: : basic bp *

Be on the lookout for compilation errors caused by non-Pick licensee problems, such as: HUSH/NOHUSH (use: echo on/off) INCLUDE item.name FROM file.name (use: include file.name item.name) PERFORM (use: execute)

Assembling User Exits

In addition to compiling your Pick/BASIC programs, you will have to re-assemble your assembly language routines. The assembler is considerably different from R83, so you may even need to rewrite some of your code to get it to function properly.

Commercial Software Considerations

If you have Jet, Accu-Plot, Desqtop, Mainlink, or any of the other commercial software available for Pick, you will probably have to obtain that product for your new Advanced Pick system, or perhaps pay a new licensing fee. Contact your Pick dealer for details.

Custom Software Considerations

If you are using custom-written software from a vendor compa ny, you may not have the source code available. You will have to contact them to obtain a new version of their software for Advanced Pick. If the Pick/BASIC source code is not available, then you have one last hope: a de-compiler. This is a program which reads the object code (on your "old" system) and produces source code (on your "old" system). There are a few that have such packages available, or provide a de-compiling service for a fee. Check your PickWorld magazine or Pick HITS catalog for possible references.


What follows is a sample checklist to upgrade from, say, R83 v3.1 on a 386 computer to Advanced Pick/Native v5.2.0 on a different 386 computer.

On the R83 machine:

1) For the SYSTEM account, do: * Examine the account for DX'ed or DY'ed files. LIST MDS WITH A1="DX" OR A1="DY" Edit the files appropriately. * Save any non-Pick files: LISTFILES SYSTEM (pick which ones you want to save, and) T-DUMP MDS filename * Save the procs (if any). SSELECT MDS WITH A1="PQ" T-DUMP MDS *

2) Find out what accounts are on the system. LISTFILES SYSTEM An alternative command to use would be: LIST-FILE-STATS (This is especially useful if you will have to create the files on the AP side.)

3) For the SYSPROG account, do: * Examine the account for DX'ed or DY'ed files. LIST MD WITH A1="DX" OR A1="DY" Edit the files appropriately. * Save any non-Pick files: LISTFILES (pick which ones you want to save, and) T-DUMP MD filename * Save the procs (if any). SSELECT MD WITH A1="PQ" T-DUMP MD * * Decatalog any Pick/BASIC programs in the BP file you need, and then save the file. DECATALOG BP * SSELECT BP * T-DUMP BP * * Confirm that the save is reliable. Verify the save using 'T-VERIFY account.name (AEFPT)', or using the "dummy" 'SEL-RESTORE non.existent.account (F)'.

4) For all other non-Pick accounts, do: * Examine the account for DX'ed or DY'ed files. LIST MD WITH A1="DX" OR A1="DY" Edit the files appropriately. * Decatalog any Pick/BASIC programs. DECATALOG basic.file * * Save the account. SAVE account.name (DFIPST) * Confirm that the save is reliable. Verify the save using 'T-VERIFY account.name (AEFPT)', or using the "dummy" 'SEL-RESTORE non.existent.account (F)'.

5) Do steps (1) through (4) twice, so you have two sets of backups.

On the AP machine:

6) Install Advanced Pick on the target machine as per the Installation Guide.

7) Customize the 'dm' account. * Coldstart routines * User logon items. * Terminal and Printer devices. * Custom procs. * Custom programs.

8) Restore each account. * Restore the account account-restore account.name 500 (z) * Update the account to Advanced Pick format. update-account account.name * Resolve any problems encountered and logged to the 'dm > clashes,account.name' file. * Compile any Pick/BASIC programs (items). basic file.name * Resolve any compile errors you might get.

9) At this point, the system is upgraded to Advanced Pick. Run whatever test routines you need to run to make you feel confid ent in the system's operation.

10) Relax.

Hopefully, this checklist will help you perform a smooth and orderly transition from your R83 system to Advanced Pick. The final installment of this series, to be published in the next issue of PickWorld, will go over the fine points of moving an Advanced Pick system to a different Advanced Pick platform.
Related tcl.set-break


Command basic.file Statement/BASIC Program
Applicable release versions:
Category BASIC Program (486)
Description compiler directive to use attribute definition items in the file's dictionary while compiling the program.

Multiple files can be specified with the same statement, separated by commas. File paths are currently not allowed in the "file" statement.

The "file" statement is typically used to allow the use of attribute definition items to identify the attribute count ("ac") of the field and automatically apply dictionary correlative codes to the field value in the item.

When the Pick/BASIC compiler encounters a "file" statement, it opens the dictionary of the file specified by "file1", creates the executable code to open the data portion of the file during execution, scans the Pick/BASIC code for references to the given file and dimensions an array with the same name as the file specified.

The size of the dimensioned array is determined by the compiler. It scans through the program looking for references to attribute names as dimensioned array subscripts (e.g. file1(credit.limit)). After it has found all references to the given file, it takes the "highest" attribute count reference derived, adds 1 to it, and uses the resulting value as the size of the dimensioned array.

After an item is read from the file, attributes within the item may be referenced by using the attribute name from the associated dictionary as the array subscript. Correlative processing codes found in the file dictionary are executed, but output-conversions are not. Values within an attribute can be specified by appending a command and a value count to the attribute name or number.

"read" and "write" statements can not specify the file.variable when the array name "file1" is used as the variable.

The file pointer is assigned to the file.variable in the form "fv.file1" and references the data section of the file opened.
Syntax file file1 {, file2 ...}
file entity
id = "100"
read entity from id then
if entity(name) = "" then crt "no name!"

The file "entity" is bound by the "file" statement.  When 
item "100" is successfully read, the "name" field is 
checked. If the name field is null, "no name" is output to the 

fv.entity = access(1)
if not(assigned(fv.entity)) then file entity

This determines if the file.variable "fv.entity" has been assigned by 
Access of the Update processor. If it has not been assigned, the 
"file" statement is executed. This technique is particularly useful 
when calling subroutines from Access, and prevents having to reopen a file each 
time the routine is called. Using this logic, the "file" statement is 
executed once.
Related basic.open