CustomWare Designs' Home Page

PRAGMA PROGRAM REFERENCE MANUAL
Index
All Operation
		Expand All ADDENDUM

PRAGMA PROGRAM REFERENCE MANUAL ADDENDUM

ANSI Sequences

View Topic

ANSI ESCAPE SEQUENCES

PRAGMA can handle ANSI sequences. The following ANSI sequences are supported :

Esc[r;cH Move cursor to row r, column c (SCP)
Esc[r;cf Move cursor to row r, column c (SCP)
Esc[xA Move cursor x positions up (MCU)
Esc[xB Move cursor x positions down (MCD)
Esc[xC Move cursor x positions right (MCR)
Esc[xD Move cursor x positions left (MCL)
Esc[2J Erase screen and home cursor (ES)
Esc[x;...;xm Set attributes/colors (SFC, SBC)
Esc[s Save cursor position (GCP etc.)
Esc[u Restore cursor position (etc. SCP)

When PRAGMA encounters one of the above ANSI escape sequences in a DISPLAY statement, it is intercepted. PRAGMA then converts the escape sequence into a call to one of the standard verbs (SCP, MCU, MCD, MCR, MCL, ES, SDA, SFC, SBC). The ANSI sequence is NOT passed through to the screen. This would not work for every screen, as some screens do not understand ANSI. Instead, PRAGMA converts this escape sequence into a call to one of the standards above, all of which use the terminal information in TERMINFO.LBS to send the appropriate control characters to the screen. If the screen is an ANSI screen, of course the terminal code would probably rebuild the identical ANSI sequence, and send it to the screen. But if the terminal is a Kimtron, or something else that does not understand ANSI sequences, the terminal code would send out the control characters that screen needs.

If an escape sequence is encountered that PRAGMA does not support, it is sent out as is to the screen. Also, if an erroneous sequence is encountered, it too is sent out as is. This is supported for those who wish to do weird things with the screen that PRAGMA does not understand. But you must realize that in doing so PRAGMA may then lose track of the cursor position and possibly the character attributes. You can force PRAGMA into synchronism again with the screen, as far as cursor position is concerned, if the screen has the ability to read its cursor position, by then executing a GCP command. This will cause PRAGMA to read the cursor position from the screen and set its internal counters to this value.

By default the relative cursor positioning ANSI commands do not operate identically to "normal" ANSI codes. They will wrap, and will cause the screen to scroll if moving past the bottom line.

The option ANSI WRAP = NO in PRAGMA.DES disables wrapping when displaying the ANSI relative cursor movement commands, like Esc[A. This enabling and disabling of wrapping applies only to ANSI commands that are displayed. It does not affect the relative cursor positioning control characters like ^H, for example. Nor does it affect the cursor positioning standard verbs like MOVE CURSOR LEFT, etc. These will always wrap.

ASCII Values Table

View Topic

ASCII VALUES

RELATIVE CHARACTER VALUES IN PRAGMA

PRAGMA sorts numbers and expressions according to their relative value (rank); lower values are placed ahead of higher values. Numbers are lower in value than control characters and expressions and are sorted in numeric order. Expressions and control characters are sorted according to the relative values shown in the table on the next pages; control characters are sorted ahead of displayable characters.

PRAGMA compares two expressions on a character by character basis proceeding from left to right. When it encounters two characters that are different, it stops and places the expression with the lower-valued character ahead of the other expression. For example, the first of the two expressions below is placed ahead of the second because a space has a lower value than "!":

"AN EXPRESSION TO REMEMBER"
"AN EXPRESSION!"

In the following example, the expression "246" is placed before the expression "25" because "4" is lower in relative value than "5":

"246"
"25"

In the next example, the number 25 is placed before the number 246 because it is a smaller number:

25
246

ASCII VALUES TABLE

The following table lists the ASCII character values you can use for communication with devices attached to your serial I/O ports. The values are shown in decimal and hexadecimal. The underline character (Hex 5F, ASCII 137) cannot be used alone as a separate character by PRAGMA. If PRAGMA receives an underline character it is converted to a hyphen.

ASCII Character Hex

0 @ (NUL) Null 00
1 A (SOH) Start of Heading 01
2 ^B (STX) Start of Text 02
3 ^C (ETX) End of Text 03
4 ^D (EOT) End of Transmission 04

5 ^E (ENQ) Enquiry 05
6 ^F (ACK) Acknowledge 06
7 ^G (BEL) Bell 07
8 ^H (BS) Backspace 08
9 ^I (HT) Horizontal Tabulation 09

10 ^J (LF) Line Feed 0A
11 ^K (VT) Vertical Tabulation 0B
12 ^L (FF) Form Feed 0C
13 ^M (CR) Carriage Return 0D
14 ^N (SO) Shift Out 0E

15 ^O (SI) Shift In 0F
16 ^P (DLE) Data Link Escape 10
17 ^Q (DC1) Device Control 1 11
18 ^R (DC2) Device Control 2 12
19 ^S (DC3) Device Control 3 13

20 ^T (DC4) Device Control 4 14
21 ^U (NAK) Negative Acknowledge 15
22 ^V (SYN) Synchronous DLE 16
23 ^W (ETB) End of Transmission Block 17
24 ^X (CAN) Cancel 18

25 ^Y (EM) End of Media 19
26 ^Z (SUB) Substitute 1A
27 ^[ (ESC) Escape 1B
28 ^\ (FS) File Separator (S1) 1C
29 ^] (GS) Group Separator (S2) 1D

30 ^^ (RS) Record Separator (S3) 1E
31 ^^ (US) Unit Separator (S4) 1F
32 (space) 20
33 ! (exclamation point) 21
34 " (quotation mark, double) 22

35 # (number sign) 23
36 $ (dollar sign) 24
37 % (percent sign) 25
38 & (ampersand) 26
39 ' (apostrophe) 27

40 ( (left parenthesis) 28
41 ) (right parenthesis) 29
42 * (asterisk) 2A
43 + (plus sign) 2B
44 , (comma) 2C

45 - (hyphen, minus sign) 2D
46 . (period) 2E
47 / (slash) 2F
48 0 (zero) 30
49 1 (one) 31

50 2 (two) 32
51 3 (three) 33
52 4 (four) 34
53 5 (five) 35
54 6 (six) 36

55 7 (seven) 37
56 8 (eight) 38
57 9 (nine) 39
58 : (colon) 3A
59 ; (semi-colon) 3B

60 < (less than) 3C
61 = (equal sign) 3D
62 > (greater than) 3E
63 ? (question mark) 3F
64 @ (at sign) 40

65 A 41
66 B 42
67 C 43
68 D 44
69 E 45

70 F 46
71 G 47
72 H 48
73 I 49
74 J 4A

75 K 4B
76 L 4C
77 M 4D
78 N 4E
79 O 4F

80 P 50
81 Q 51
82 R 52
83 S 53
84 T 54

85 U 55
86 V 56
87 W 57
88 X 58
89 Y 59

90 Z 5A
91 [ (left bracket) 5B
92 \ (back slash) 5C
93 ] (right bracket) 5D
94 ^ (caret, not equal to) 5E

95 ^ (underline, PRAGMA can't use alone) 5F
96 ` (Reverse apostrophe) 60
97 a 61
98 b 62
99 c 63

100 d 64
101 e 65
102 f 66
103 g 67
104 h 68

105 i 69
106 j 6A
107 k 6B
108 l 6C
109 m 6D

110 n 6E
111 o 6F
112 p 70
113 q 71
114 r 72

115 s 73
116 t 74
117 u 75
118 v 76
119 w 77

120 x 78
121 y 79
122 z 7A
123 { (left brace) 7B
124 | (broken vertical bar) 7C

125 } (right brace) 7D
126 ~ (equivalence sign) 7E
127 (DEL) Delete 7F

About PRAGMA

View Topic

About the PRAGMA Editor

View Topic

ABOUT THE PRAGMA EDITOR

The PRAGMA Editor program is the maintenance program for the PRAGMA standards, messages, references and description parameter files.

INSTALLING AND RUNNING

The PRAGMA System Editor is a compiled PRAGMA program, and therefore you must set the operating system environment as for interpreted PRAGMA. For complete information please consult Environment Configuration in the PRAGMA System manual or the PRAGMA online help.

To run the PRAGMA Editor program you must have the following files:

PREDIT.EXE (predit for UNIX)
PREDIT.DES (or a suitably configured PRAGMA.DES)
PRMSG.PFM
TERMINFO.LBS

PRAPRINT.PFM (optional)

PRAREF.PFM
PRAREF2.PFM
PRADES.PFM
PRMSG2.PFM
PRSTD.PFM
TERMINFO.LBS

PREDIT.EXE (predit for UNIX) is the executable file that contains the application and is different for every operating system (MS DOS, OS/2 or UNIX).

The remaining files are always the same, regardless with which operating system they will be used.

PREDIT.DES is the text file that contains various initialization parameters for PREDIT.EXE. If PREDIT.DES is not present, PRAGMA.DES will be used. PREDIT will not run correctly unless the following parameters have been defined:

RECORD SIZE = 16384 (minimum, for the help text)
PFM NUMERIC REFS = YES
INPUT RESET KEY = ^W (or whatever you want, but not ESCAPE)
PRINTER = LPT1 (or wherever your printer is, if you want
to print)
FILE RECORD NAME FOR PRINTING = HP-LASERJET-GOTHIC
(or whatever you want, if you want to
use PRAPRINT.PFM to initialize the
printer)

You may also have to make some changes to the color parameters, depending on whether you use a monochrome or color monitor.

The easiest way to edit the description file is using the online help program of PRAGMA.

PRMSG.PFM and PRAREF2.PFM are the same files used by PRAGMA and they contain all the messages, windows and the help text.

PRAPRINT.PFM is an optional file that contains printer initialization records. It is only used if you want to initialize your printer with the record specified in the FILE RECORD NAME FOR PRINTING statement in the description file. PRAPRINT.PFM can be viewed and edited with the PRAGMA online help.

TERMINFO.LBS is a text file that describes the characteristics of the terminal. It is expected to be in the directory where PRSCR.EXE is or you can put it into a subdirectory called \USR\LIB\TERMINFO. Do not forget to put the appropriate SET TERM statement into your CONFIG.SYS, otherwise you will get a "Screen Initialization error, ABORTING" message.

To run the PRAGMA Editor program simply type PREDIT. The copyright screen will appear. To continue, just hit any key, and you will come to the main menu.

The submenus are displayed by either hitting the <ARROW DOWN> key or the <RETURN/ENTER> key when your requested choice on the horizontal main menu is highlighted.

If the colors are hard to read, make sure that SET TERM has been set correctly, either for color or monochrome. You may also have to edit the color parameters in the description file.

About the PRAGMA Screen Generator

View Topic

Accessing the File SCREENS.PFM

View Topic

Active Keys in the Screen Editor

View Topic

ACTIVE KEYS IN THE SCREEN EDITOR

ESC EXIT Quits the editor and goes back to the
menus.

F1 HELP Displays help text with a listing of
the active keys inside the editor.

CURSOR MOVEMENTS

ARROWS Text mode (default) move the cursor
without writing to the screen.

Line mode move the cursor and display
the appropriate line symbols.

CTL-LEFT ARROW Moves the cursor to the left margin.

CTL-RIGHT ARROW Moves the cursor to the right margin.

<-- BACKSPACE Moves the cursor back and erases.

RETURN Moves the cursor down one line to the
left margin.

HOME TEXT MODE Moves the cursor to the upper left
corner of the screen.
LINE MODE Draws the upper left corner of a box in
the chosen line symbol.

PgUp TEXT MODE Moves the cursor to the upper right
corner of the screen.
LINE MODE Draws the upper right corner of a box
in the chosen line symbol.

End TEXT MODE Moves the cursor to the lower left
corner of the screen.
LINE MODE Draws the lower left corner of a box in
the chosen line symbol.

PgDn TEXT MODE Moves the cursor to the lower right
corner of the screen.
LINE MODE Draws the lower left corner of a box in
the chosen line symbol.

SCREEN MANAGEMENT

ALT-M MOVE Marks the beginning point of a move.
The selected screen portion can be moved
with the arrow keys and inserted by
hitting the return key

Del CUT Marks the beginning point of a cut.
The cut screen portion is stored in the
clipboard.

ALT-C COPY Marks the beginning point of a copy.
The copied screen portion is stored in
the clipboard.

ALT-P PASTE Marks the beginning point of a paste
from the clipboard. The stored screen
portion is pasted in the attribute and
colors that are active at the moment of
paste.

Ins PASTE Marks the beginning point of a paste
from the clipboard. The stored screen
portion is pasted in the original
attribute and colors.

LINES

ALT-B FULL BOX Marks the beginning point of a filled
box drawn in the chosen line symbol.

F5 EMPTY BOX Marks the beginning point of an empty
box drawn in the chosen line symbol.

ALT-H HOR. LINE Marks the beginning point of a horizontal
line drawn in the chosen line symbol.

ALT-V VERT. LINE Marks the beginning point of a vertical
line drawn in the chosen line symbol.

ALT-J JOIN LINES Inserts an appropriate symbol to join
the lines.

JOIN ALL Marks the beginning point of an area
in which all lines are joined with an
appropriate symbol.

F9 TOGGLE Toggles between text mode and manual
line draw mode.

CTL-F9 LINE STYLE Changes the line style.
CTL-F10 LINE STYLE

TEXT MANAGEMENT

F6 LINE SYMBOLS Opens a window that displays line
symbols. A symbol can be selected and
put into the clipboard.

SHIFT-F6 ALPHA SYMBOLS Opens a window that displays various
alphabetical symbols. A symbol can be
selected and put into the clipboard.

CTR-F6 MORE SYMBOLS Opens a window that displays more
symbols. A symbol can be selected and
put into the clipboard.

ALT-T TEXT Marks the beginning point for inserting
imported text.

F3 ADVANCE TEXT Advances the imported text.

ALT-S SHOW TEXT Shows the remainder of the imported text.

COLOR MANAGEMENT

CTL-F1 FOREGROUND Changes the foreground color.
CTL-F2 COLOR

CTL-F3 BACKGROUND Changes the background color.
CTL-F4 COLOR

CTL-F7 ATTRIBUTE Changes the attribute.
CTL-F8

Binary Data

View Topic

BINARY DATA

WHAT IS BINARY DATA

You cannot use binary data in PRAGMA 4, but you can import binary data into a noun and then export binary data back to the operating system. The main reason for PRAGMA 4 to have the capability to handle binary data is to be compatible with PRAGMA 5.

A binary data file is a file that contains a picture, sound, an executable, the vocab or something similar. Binary data has to be handled differently because it may contain the ASCII character zero, which is used in ordinary data files as an end of file character.

A picture is usually stored as a binary data file. The picture element in PRAGMA 5 understands bitmap files, which are binary files that contain all the information to display a picture. It is possible to store all the pictures a program needs as binary files on the operating system, and this is probably what you would do if you only need a few different picture. But to store hundreds of pictures on the operating system for say a personnel database, with a picture of every employee, soon becomes impractical.

It is therefore preferable to import the binary data into a PRAGMA noun and then add the contents of the noun to a file record.

This feature of importing and saving binary data in a file opens up a lot of exciting possibilities. But remember that usually binary data files are large. A decent picture can easily consist of a few hundreds of kilobytes. And the kilobytes quickly add up, requiring a large hard disk. Also remember that PRAGMA will have to deal with a lot of bytes, necessitating a powerful computer to accomplish the task quickly. By and large, remember that picture management is one of the most computer intensive tasks.

USING BINARY DATA

PRAGMA lets you import into a noun a file containing binary data. Once the binary data is in a noun, you can copy it to another noun or store it in a file record.

When using binary data be aware that most of the time you are working with large files and it is easy to waste memory.

For instance, if a large binary noun value is COPYed around to other nouns, the source noun will still contain the copy of the large value. Thus, multiple copies of the large value will be eating up a lot of memory. It is thus suggested that you COPY null ("") to the source noun after you have COPYed the value somewhere. This will free up the memory used by the original copy of the value.

Also be aware that if you are using WRITE NOUNS = YES in the description file, the vocab will also contain all the large binary noun values your program has last used. This will cause the vocab file to grow immensely. It is thus also suggested for this reason that you null out nouns that hold binary values when you are through with them.

The standard verbs CUT, JOIN, and IF all work on binary data. A binary value may be CUT after either a number of characters, a character string, or another binary value. When performing an IF with binary data, the hierarchy is such that binary is less than numeric which is less than ASCII. In a JOIN, if either or both of the pieces are binary, the result will also be binary.

Some verbs, like ADD, INPUT STRING, etc., will crash with an Invalid Numeric Value error, or with the new Invalid ASCII Value error, if they encounter binary data in a noun. Other verbs, like DISPLAY, will simply ignore binary data.

The Btrieve file manager cannot handle binary data in file records at the moment. Likewise, the Pragma Fileserver cannot handle binary data. ONLY PFM can handle binary data in the nouns of file records. If you attempt to save a record containing binary nouns into a Btrieve or Fileserver file, you will get INTERNAL LOGIC ERROR in EXTERNAL ECHO. Also, binary nouns cannot be used as the reference of a PFM file; only the data nouns can be binary.

The file record size set in PRAGMA.DES must be very, very big if you plan to use binary nouns, otherwise you will get REFERENCE TOO LONG in EXTERNAL ECHO. Unfortunately, one often does not know the largest file record to expect, as binary data varies greatly in size. Thus, you must set a very huge record size, just to be sure to have enough room. This is very wasteful of memory, as this buffer is occupying a lot of memory for no good purpose, except when getting or saving a record.

At present, there is a limit of 1 MB for the maximum size of binary data a noun can hold.

COMIO Communication Handler for DOS

View Topic

THE COMMUNICATION HANDLER COMIO

COMIO.COM is a serial communications interrupt handler that is used both by PRAGMA and P4TERM under DOS. It is a TSR (terminate stay resident) program that must be loaded into the background, specifying the proper parameters, before either PRAGMA or P4TERM are started.

If COMIO is not loaded, PRAGMA and P4TERM are still able to communicate with the serial ports, but the communications will be done strictly in a polled manner, which means that data may be lost at high speed, or if the two systems are not synchronized. It is not recommended to run PRAGMA or P4TERM without COMIO if serial communications are planned.

COMIO can also change the settings of the serial port parameters (baud rate, parity, data and stop bits) via the command line.

LOADING COMIO

COMIO is loaded from the DOS command line or from AUTOEXEC.BAT.

The optional command line parameters for it consists of a forward slash (/) followed immediately by the parameter letter or number. With parameters that also specify a numeric value, this number follows immediately after the parameter letter, with no intervening spaces. Parameter letters may be either upper or lower case. All parameters expect no embedded spaces or other foreign characters, except where shown.

The possible commands are :

/Bxxxx Set buffer size. Can only be done when initially loading
COMIO. Maximum size is 4096. Default size is 512.

/Txxx Set receive timeout for all ports. Units are clock ticks
(18.2 per second). Thus, /T182 is equivalent to 10
seconds, and is also the default. Maximum value is also
182.

/E Empty the internal buffers (throw away all data).

/0 Disable the driver. When disabled, control is returned to
the former serial port handler (usually the system BIOS
code in ROM), and the interrupt vectors are unhooked.
Also clears the buffers.

/1 Enable the driver. Takes over the control from the former
code (which is probably the system ROM BIOS), and hooks the
vectors.

/X Select Xon/Xoff protocol for all ports.

/N Select no protocol for all ports. This is also the
default.

/COMX:96,N,8,1
Set the serial port parameters of the specified communication
port. The format is the same as the MODE command in DOS,
except that the complete list of parameters must always be
used, as shown in the example.
The possible values for the baud rate parameters are:
12 - 1,200 baud 19 - 19,200 baud
24 - 2,400 baud 38 - 38,400 baud
48 - 4,800 baud 57 - 57,600 baud
96 - 9,600 baud 115 - 115,200 baud

When COMIO is loaded, it makes sure it has not been loaded before. If it has, the second copy of COMIO updates the first copy. The /E, /0, /1, /X, /N, and /T parameters can be used in this way, to reconfigure COMIO after loading it. The /B parameter can only be used to set the size of the buffers when COMIO is initially loaded.

The serial port parameters can be set or changed at any time, even after COMIO has been loaded.

The /0, /1, and /E parameters are mutually exclusive. If they are used together, whichever of them is specified last overrides the others.

COMIO maintains separate send and receive buffers for each of the four com ports (COM1-4). All of these buffers are the same size. This size can be set with /B, or it is 512 by default.

COMIO supports the standard com ports only. It does not support multiport boards like the Hostess. It assumes the standard base addresses and interrupt lines for these four ports. COMIO takes over BOTH IRQ 3 and IRQ 4. This cannot be changed.

USING COMIO WITH PRAGMA

Usually you will be using COMIO with its default settings. To do this use the following command:

COMIO

If you need to use the Xon/Xoff protocol, start COMIO this way:

COMIO /X

USING COMIO WITH P4TERM

When P4TERM communicates with a UNIX computer you should always use the Xon/Xoff protocol. In this case start COMIO the same way:

COMIO /X

See Also:

Installing PRAGMA on DOS
Running PRAGMA on DOS
P4TERM - Installation
P4TERM - Running

Color Management

View Topic

COLOR MANAGEMENT

The attribute setting and color setting interact. It is important that you ALWAYS set attributes BEFORE setting colors. If you set attributes AFTER setting colors, the attributes that you set will also clear the colors to black and white (on a color screen of course).

PRAGMA lets you know if it is operating with a color or a monochrome screen. The standard noun COLOR SCREEN will contain a 1 if the screen supports colors, otherwise it will contain a zero. COLOR SCREEN is set to the appropriate value every time PRAGMA is started.

The attribute underline has no counterpart on a color screen, and if used there (without setting any colors), underline becomes a blue foreground. The bold and blinking attributes will affect the foreground color, but again, you must set them BEFORE choosing the color or else the colors get reset to white foreground and black background. The inverse attribute reverses foreground and background colors. The underline and inverse attributes cannot be used together on a monochrome screen, and PRAGMA always gives precedence to the underline attribute. If both underline and inverse are chosen, only underline will appear. On a color screen, if inverse and underline are both chosen, you get blue foreground on a white background.

The bold and blinking attributes are not affected by color setting.

There are terminal descriptions in TERMINFO.LBS called dosansimono, dosmemmono, os2ansimono, and ansimono. There are meant to be used with a monochrome screen. The only difference is that the SET FOREGROUND COLOR and SET BACKGROUND COLOR commands do nothing. Setting of colors when using these terminals types is ignored. This is important because color setting will clear the inverse and underline attributes since these are really colors on the color screen and not attributes.

Should you want to know which terminal description PRAGMA is using from within PRAGMA, the standard noun TERMINAL NAME will contain the name of the used environment variable.

Since color setting MUST be done AFTER attribute setting, this can cause a problem on a monochrome screen. For instance, you may want to write an application that can run on BOTH a monochrome screen and a color screen. On the monochrome screen, you want to use inverse, whereas on the color screen you want some colors. You can write your verbs to select the inverse attribute followed by selecting the colors for the color screen. Since on a color screen the colors being set after the attributes will clear inverse video (which in reality is the foreground color black and the background color white), you will get your colors as desired. But this is no good for a monochrome screen; here you WANT the inverse and not the colors. Of course the monochrome screen will not be able to display the colors, and the ANSI driver will thus simply give you a light foreground with dark background when you attempt to set the colors (which is normal video), thus overriding the inverse video that you wanted. The solution is in using the xxxmono terminal type to cause the color selections to be ignored, and the inverse will then still be selected.

The inverse video characters ^N and ^O, the ANSI attribute commands (^[7m and ^[0m), and the SET DISPLAY ATTRIBUTE command when used with ATTRIBUTE INVERSE or ATTRIBUTE NORMAL on a color screen, swap the foreground and background colors. These commands cause attribute commands to be sent to the screen, which are then followed by color commands if the screen is a color terminal.

Compiling - Basics

View Topic

COMPILING - BASICS

INTRODUCTION

You do not need to have any knowledge of the C language to successfully translate your PRAGMA applications to C and then compile them for DOS, OS/2 or Xenix.

A compiled PRAGMA program utilizes the same environments and is subject to the same advantages and restrictions of the operating systems like the interpreted program from which it originates.

Compilation gives it some advantages, like speed and sourcecode security. The disadvantage is that once compiled a program can no longer be changed without going through the whole compilation process again.

Before you start compiling an application it should run without errors in the interpreted mode in the operating system of your choice.

If you have an application written in PRAGMA 3, you must convert it to run in interpreted PRAGMA 4 in the operating system of your choice.

Since the compiled PRAGMA is so closely related to interpreted PRAGMA 4, a good knowledge of the interpreted PRAGMA and its requirements on operating systems are a must, but you would not be reading this if this were not the case.

You may translate and compile your application under DOS, OS/2 or SCO UNIX, provided that you have the necessary compilers.

Although we have made everything as simple as possible, there are a few things you just must know to do a successful compilation of a PRAGMA program. These things are explained in the following pages.

To compile, the first step will be to install the C compiler on your machine. Nothing very complicated, but take your time and be careful to do it right. Also take care to set the additional parameters of your environment correctly.

Then you are ready to translate to C and compile. Please don't run before you have learned to walk. Write a few simple verbs and get the feel of everything. Then undertake more ambitious projects.

GENERATING C SOURCECODE

The standard verb TRANSLATE TO C (TRC) generates generic C sourcecode that can be compiled and linked with the supplied libraries to generate executable programs that run under DOS, OS/2 or SCO UNIX 386. And this regardless of which operating system the C code was generated on. For more information about TRANSLATE TO C please consult the online reference.

The verb TRANSLATE TO C directly reads the vocabulary from the PRVOCAB file. All programs are translated on a line by line basis, i.e., each PRAGMA source line is translated into one C source line.

The execution library contains individual C functions named after the PRAGMA verbs they replace.

VERBS

Each PRAGMA verb is translated to a C function and must therefore receive a legal C name.

All characters that are not part of the alphabet which occur in the names of verbs and nouns are translated to underlines since C does not accept nonalphabetic characters in the names of functions. Make sure that you don't unintentionally create duplicate names of functions this way. Linking aborts if it finds duplicate names of functions.

The only legal characters are A-Z, a-z and 0-9. This does not mean that you have to rename everything in your whole application to abide by this; the translation process does that for the generated code by itself. It is only necessary to be aware that duplicate names may be created during this process, and then you HAVE to rename one of them in the vocabulary, and start the translation over.

If your verb name starts with a number, the translator joins an underline to the start of the name. Again, beware of duplicates.

For example, a verb called HELLO+ (a legal name in PRAGMA), will translate to HELLO^, which is OK. But if you also have a verb called HELLO-, it will be also translated to HELLO^ and you have the duplicate names problem. The solution is to rename HELLO+ to HELLO PLUS and HELLO- to HELLO MINUS, for instance.

Only the first eight characters of the vocabulary name are used for an operating system filename used to store the source code in. The extension .C is automatically added. An attempt is made to open the file which has just been created. If it already exists, this name is rejected. A counter is then added to the name to produce a new name. This count begins with 1, and after it reaches 10, it becomes a two digit count, the maximum being 99.

This count is appended to the filename or it replaces the last character(s) in the filename if the total length would exceed 8. This is done until a unique filename is found or until the count reaches 100, when it aborts in disgust.

The same file is used for the C source until either of two conditions occur: the first eight characters of the PRAGMA vocabulary name becomes different from the preceding verb, or the file size exceeds 32k bytes. If the name becomes different, a new filename is created and opened, as explained above. If the file size reaches the limit, the next filename is created by attaching a numerical appendage to it as explained above.

The execution library contains C functions named after the PRAGMA verbs they replace. All standard verb and noun names in the execution library are in English. In non-English countries this may cause a conflict in names between a standard routine in the library, and a user created word.

The entry point into the program is the verb "AUTOEXEC". If there is no AUTOEXEC verb in the vocabulary, it cannot link. This is similar in usage to the interpretive runtime system, in that this is the point from which the execution of your program starts. It is usually a main menu verb.

COMMENT is emulated by enclosing the comment text between the C delimiters (/* and */) in the actual C sourcecode. Comments may not contain these delimiters. There is no check for this, so beware! If your COMMENT has these special characters, you have to ALTER the verb to correct the situation and then retranslate.

DIVIDE To closely emulate interpreted PRAGMA, a divide by 0 (zero) does not cause the program to abort (as it really should) but it assigns the value of numeric zero to QUOTIENT. Please take note that this is mathematically highly irregular. Your program should trap any divide by zero.

NOUNS

All characters in the names of nouns that are not part of the alphabet are translated to underlines, since C does not accept non-alphabetic characters in the names of nouns.

Make sure that you don't unintentionally create duplicate names of variables in this way. If two names differ only by a non-valid C character, they convert to the same variable name and then cause a linking error.

Also ensure that no noun names duplicate within the first 25 characters. This is because during conversion a few characters are attached to the front of the noun names. And since C has a limit of 31 character names, again you could unintentionally create duplicate names of variables.

RESERVED WORDS

The C language has several reserved words. Since PRAGMA when compiling interacts with the C language these words have to be taken into account. Most of the reserved words in C are in lower case and luckily PRAGMA was designed to be mostly upper case, although it allows lower case as well. In UNIX and C case in names is significant, as it is in PRAGMA. So if all C words were in lower case and all PRAGMA words in upper case, there would be no problem. But there are a handful of C words that are in upper case. We do not have a complete list of these words and they may vary from system to system.

The following words are reserved in C and should not be used for names of PRAGMA nouns, verbs or files. If you are currently using them just RENAME them to avoid potential problems. It doesn't matter if you use reserved nouns for LABELS in PRAGMA since the characters LABEL^ are stuck in front of them.

ARGC
ARGV
COUNTER
EOF
NULL
OK
RETURN^CODE
MSDOS

LABELS

The method used to produce label names is the same as the one described for vocabulary nouns, except that the characters LABEL^ are added to the front of the name.

If a label name starts with a number, that number is kept since it does not interfere in the C sourcecode.

If two LABELS differ only by a non-valid character, they are converted to the same name and cause an error. You have to ALTER a verb that has this problem.

FORMS

Should your vocab contain any forms from PRAGMA 5, make sure that they are not included in any verb that you plan to translate to C. They are not supported when you are compiling in the environment for PRAGMA 4 and will generate a compiler error.

See also:

Compiling - In Depth
Compiling - Generating C Sourcecode

Compiling - Generating C Code

View Topic

COMPILING - GENERATING C SOURCECODE

In the subdirectory PRAGMA (or whatever you called it), keep the PRAGMA program you want to translate. Make sure that it runs correctly from the verb AUTOEXEC.

Although not strictly necessary, we strongly suggest you work with a copy of your program. A lot of files will be added later on, some of which you will want to delete. And you will not want to accidentally delete the only copy of your program.

Run the verb TRANSLATE TO C (TRC). The program will perform an initialization and then prompt you to answer some questions.

Name of item to translate

TRANSLATE TO C operates similarly to SELECTIVE SAVE, in that it marks a tree or trees of items, and only those items marked are translated. You do not have to selective save the items you want to translate.

TRANSLATE TO C will first ask for items to mark. When constructing a program, you simply mark everything from the verb AUTOEXEC and nothing more. The feature of marking more than one item is only needed to build libraries, which is explained in the Libraries section.

Name of item to exclude

If you have previously translated some verbs and made them into a library, this prompt lets you skip over these verbs. All items typed here will be unmarked, just like the marking process in reverse. At the end of this process you will have remaining as marked only those programs which need to be translated to C.

If you are not usinge a previously created library simply skip over this question.

Name of destination file

This prompt asks for the name of the destination file. Type the name of the executable file you want to create, without any extension. The name must be a legal filename. In this example we will use the name PRATEST.

Press RETURN if creating an executable file,
or ESCAPE if creating a library

This prompt asks whether this file will be a program or library. Answer executable file.

Enter the path to the file HIO.DEF (OS/2 only)

This prompt asks for the path to the file HIO.DEF. This file is only needed when linking for OS/2. Simply type RETURN in all the other cases. In OS/2 HIO.DEF is used by the OS/2 MAKE file. No backslash is needed at the end of the path.

Names of the libraries to be used to create this program.

This prompt asks for a list of the libraries to use when linking this program. If you are not using any of your own libraries, you can ignore the question.

If you are using your libraries you must answer this question correctly, in accordance with what you have unmarked above or linking will not complete. You must NOT use wildcart characters. Each library must be specified individually. Path names may be added if needed.

After having answered the last prompt TRANSLATE TO C will generate a C sourcecode file for every verb in your application plus the following files, assuming that you used PRATEST as filename:

PRATEST.DOS
PRATEST.OS2
PRATEST.XNX

PRATEST.LL
PRATEST.OL

The files called PRATEST.DOS, PRATEST.OS2, and PRATEST.XNX are MAKE files for the compilers of the various operating systems you want to compile and link your application in. .DOS is for the MS-DOS environment, .OS2 for OS/2, and .XNX for UNIX.

PRATEST.LL is a file needed only for DOS and OS/2, not for UNIX. It contain lists of the object modules and libraries used to create the executable program.

Be aware that generating C sourcecode is a lengthy process, especially if you have a large vocabulary.

See also:

Compiling - Basics
Compiling - In Depth

Compiling - In Depth

View Topic

COMPILING - IN DEPTH

NOUNS

Variable length nouns are more properly called variable storage nouns - each assignment of a value to one causes a reallocation of a character array to the exact size needed to store the value. This may not be too fast but it covers every case encountered by a PRAGMA verb.

All user nouns are defined in the source module(s) NOUNxx.C. All nouns are global. All nouns are referenced as external by all procedures. An "xx" is the optional counter added to the filename if necessary.

All standard nouns are defined in the module STDNOUN.C. This module is part of the runtime library.

The source files for the nouns are of the format NOUNxx.C (in which xx is the optional counter). The file for the numerics is NUMBER, the file for the layouts is LAYOUT, and the file for the strings is STRING.

FILES

All files are global and are referenced as external by all procedures.

Each file is defined in a separate source module whose name is created by the procedure described for function names.

Each file has a structure of control data allocated to it, like nouns. This structure is defined in file.h, and is explained below:

struct file
{
unsigned char openflag;
char openmode;
unsigned char mockflag;
unsigned char cond;
unsigned char *fcbptr;
unsigned int keysize;
unsigned int fieldcount;
struct noun this;
struct noun shortname;
struct noun longname;
struct noun *keynumber;
struct noun *(field[numberofnouns]);
};

openflag is a flag to tell whether or not the file has been opened. Any access implies this file is open, and all files are left open for the duration of execution. A zero value means closed, a one means open.

openmode is the fast/safe mode for Btrieve. This corresponds directly to the mode described in the Btrieve manual in the discussion of the open command. This is the field that you have to edit if you want to make a file fast mode for Btrieve. It cannot be used with PFM files.

mockflag tells whether this file needs mock internal or mock external emulation (both of which are really the same thing). A 0 means no emulation, a 1 means internal emulation, a 2 means Fileserver emulation.

cond is a flag used in conjunction with the this pointer for file positioning.

fcbptr is a pointer to control data for this file. It is used with either PFM or Btrieve.

keysize is only valid when the file uses mock internal or mock external emulation. Otherwise it is ignored. This value specifies the minimum length of the key, to which it is padded with binary zeroes if shorter. It must match the size of the key as given by the length= parameter in the description file used with PFM or Btrieve.

fieldcount is the number of nouns that belong to a record of this file. It does not include the key number noun.

this is a noun structure that contains the positioning information for this file.

shortname is a noun structure that contains the 8 character filename of this file, minus the .PFM or .BTR extension. It is used with PFM or Btrieve.

longname is a noun structure that contains the full name of this file, as in PRAGMA. It is used with the Fileserver.

keynumber is a pointer to a noun structure that contains the key number to use with this file. This is the first noun of the file definition in PRAGMA, if the file is a PFM or Btrieve file. Otherwise it is the dummy key noun inserted into the file definition during translation.

field is an array of length 'fieldcount' of pointers to noun structures. These are the second and greater nouns of the file definition in PRAGMA, if the file is a PFM or Btrieve file. Otherwise, the first one is the dummy key noun inserted during translation, and the rest are the nouns as found in the original file definition.

LABELS

Labels are in C format, followed by a ':'.

CONSTANTS

All constant values (numeric and string) are implemented as fixed length nouns. The noun names are generated when they are translated, and generally are not meaningful. The names are composed of the base name of the resulting file (default PRAGMA), an underline, a word describing the data type (LAYOUT, NUMBER, or STRING), followed by an underline and the unit number in the PRAGMA vocabulary. Example: PRAGMA^NUMBER^01F7.

They all are global and are just like other nouns with two exceptions: they do not have meaningful names and they have initial values at runtime.

See also:

Compiling - Basics
Compiling - Generating C Sourcecode

Compiling - UNIX - SCO Compiler

View Topic

COMPILING AND LINKING - UNIX - SCO UNIX COMPILER

To be able to compile a PRAGMA application under SCO UNIX you must have the complete development system installed as well as the regular operating system. For SCO UNIX 386 we use the development system version 2.3.0. The operating and development systems are purchased as a complete package known as the Development System, complete with online manual and text editor. The development system is added to the regular operating system with the program custom.

INSTALLING PRAGMA FOR UNIX

If, when installing of PRAGMA for SCO UNIX with custom, you chose the ALL option, you will already have everything needed to compile your application. Please consult the Installing PRAGMA in the SCO UNIX section for further details.

COMPILING AND LINKING YOUR SOURCE CODE

Generating the C sourcecode of your application is done from within PRAGMA with the verb TRANSLATE TO C, and is described in the Compiling - Generating C Sourcecode section.

Next you must compile and link your C sourcecode to generate an executable program. At the $ prompt type:

make -f filename.xnx

When running MAKE, you will, in addition to other files, also generate a file called filename.a. If you have to run MAKE more than once (nobody is perfect), you must first delete this file.

Every time you compile a program in UNIX you are also creating a library called Slibprogramname.a. This library is written to the /usr/lib/386 directory and is not erased after successful compilation and linking.

You may end up with a lot of libraries that are not useful to you if you don't periodically clean out that directory. But be careful not to delete the wrong ones or you may have to redo your entire UNIX installation!

If you wish you can rename your application to any other legal UNIX name.

When your compiled program starts, it will first look for the .DES file with the same name as your executable file. If the program cannot find it, it will look for a PRAGMA.DES file, and if it cannot find one, it will use defaults. This gives you the possibility of using different .DES files for different compiled programs.

WARNING Be aware that in UNIX you are not allowed to name your program test because it is a reserved word. Also don't name your application pragma, because you would be creating a library called Slibpragma.a, in direct competition with the original Slibpragma.a library, with interesting results.

See also:

Installing PRAGMA on SCO UNIX
Compiling - Generating C Sourcecode

Compiling under DOS - Compiling

View Topic

Compiling under DOS - Setting Up

View Topic

COMPILING UNDER DOS - SETTING UP

SETTING UP THE WATCOM C/C++ COMPILER UNDER DOS

To compile a PRAGMA application under DOS you have to use the WATCOM C/C++ compiler, version 10. This compiler comes with an extender, letting you compile applications that are not restricted by the 640 K barrier of DOS. But be aware that these compiled programs will run only with a 386 or better CPU.

Make sure that when you get the compiler you also get all the software patches that update it, if any. All Watcom customers may download the patches from the Watcom BBS to keep their product up to date.

It is important that you use the same version of the compiler as LBS uses. The reason for this is that you are also linking in much code of PRAGMA from the PRAGMA.LIB library, which has been compiled using a specific version of Watcom C/C++. In some cases, if you use another version when compiling your application, you may see an incompatibility between the two versions of the compiler.

You will need a lot of free space on your hard disk. The Watcom C/C++ 10 environment uses about 20 megabytes; then you will also need space for PRAGMA. During compilation you will be creating C sourcecode, object code, a library and finally the executable version of your program. And if your PRAGMA vocab is large, all this will need lots of space.

Insert the CD ROM disk in your drive and type INSTALL. As far as we know, the Watcom compiler is sold only on a CD ROM. You can, if you want, copy the contents of the CD ROM to diskettes, and then use them for the installation, although you must then shuffle around something like 51 diskettes!

The installation program will ask you to select the host operating system. Choose DOS. Again answer DOS for the target operating system. Leave the option 16 bit development selected. From the select other options screen you don't have to select any one, although the on-line help might come in useful.

Then the installation program will ask you in what directory you want to install the compiler. You may choose whatever name you want, but in the following example we chose the default name, WATCOM.

At the end you are given the choice to have the program modify for you the AUTOEXEC.BAT and the CONFIG.SYS FILES. You can choose yes, but we will tell you further on what has to be entered into those files.

After you installed the compiler, install all the available patches (if any) in the correct sequence. A batch file that comes with each patch will do this automatically for you.

To the created subdirectories, add four more:

PRAGMA will keep the program that has to be compiled, the generated C
sourcecode and object code.
PRAINCL holds the included files necessary for the compiler.
PRALIB will hold the main library used by the compiler.
PRAUTLIB will hold the libraries that you will generate.

You can use any name you wish as long as you are consistent and don't get confused, but throughout this manual we will use these names.

We use a lot of subdirectories to avoid mixing PRAGMA and WATCOM files and to keep the whole environment well laid out and easy to update.

You should end up with a directory tree looking like this:

WATCOM ^^^^^^^^^^^^^^^^BIN
|^^BINB
|^^EDDAT
|^^H^^^^^^^^^SYS
|^^LIB286^^^^DOS
|^^LIB386^^^^DOS
|^^PRAGMA
|^^PRAINCL
|^^PRALIB
|^^PRAUTLIB
|^^SRC^^^^^^^EDITDLL

SETTING UP THE DOS ENVIRONMENT

Your environment configuration must follow the same recommendations described in the PRAGMA 4 Getting Started manual. In addition, you must add the following.

Your PATH must contain the following statement:

PATH=C:\WATCOM\BIN;C:\WATCOM\BINB

Also the following additional SET statements must be active:

SET INCLUDE=C:\WATCOM\H;C:\WATCOM\PRAINCL
SET LIB= C:\WATCOM\PRALIB;C:\WATCOM\PRAUTLIB
SET WATCOM=C:\WATCOM
SET EDPATH=C:\WATCOM\EDDAT

SETTING UP PRAGMA

The PRAGMA DOS diskettes that you received contains all the necessary files to perform a successful compilation. Specifically, the following is a list of all the files supplied that pertain to compiling:

PRAGMA.LIB
COMM.LIB

MAKE.EXE

VERB.H
FILE.H
NOUN.H

The PRAGMA.LIB is the library that contains the code to compile your program. Copy it to the PRALIB subdirectory.

The COMM.LIB is the library that contains additional code to compile your program. Copy it to the PRALIB subdirectory.

MAKE.EXE is the make utility used when compiling. The make utility that comes with PRAGMA overcomes some limitations of the make utility supplied by WATCOM. Copy it to the PRAGMA subdirectory.

Copy the files NOUN.H, VERB.H and FILE.H to the PRAINCL subdirectory.

MODIFYING THE WATCOM COMPILER

The following discussion, although pertinent to the Watcom C/C++ version 10 compiler, applies to the Watcom C 9.1 compiler. Should encounter this problem with the Watcom C/C++ version 10 compiler, consult its manual on how to make these changes.

Most DOS C compilers are set by default to allow a maximum of 20 open files. Many PRAGMA applications require more than this; especially since many applications do not close files when finished with them. In these cases it is necessary to modify the C compiler runtime library to allow more open files.

When compiling PRAGMA programs, the modification of the Watcom C compiler library must be done by you because you are using your own version of these libraries and we cannot legally redistribute the Watcom libraries we use.

This modification process is explained in the Watcom documentation. However, it seems to make many assumptions. Therefore, it is explained here in greater detail.

Alter the following line in the file '\WATCOM\H\STDIO.H' :

#define ^NFILES 100 /* number of files that can be handled */

By default, it has a 20 as the number. You may change it to any desired value. We use 100 for PRAGMA 4. You do not also have to use 100, but this is recommended.

You now have to recompile three source files that contain code of the Watcom library. The files IOB.C and NFILES.C, which are found in \WATCOM\SRC\STARTUP, and the file CMAIN386.C, found in \WATCOM\SRC\STARTUP\386. In order to perform this compile, you must change directory to the directory where the file resides, and issue the following command :

WCL386 -c filename

where filename is the name of the file to compile.

This compile should produce no errors, and must result in an .OBJ file of the same base name as the .C file. Of course you must have the DOS environment set correctly for the compiler (PATHs, various SETs, etc.).

These three .OBJ files are then copied to the directory \WATCOM\LIB386\DOS. Make a backup of the current library by issuing the following command :

COPY CLIB3R.LIB CLIB3R.ORG

Then replace the original .OBJ files in the Watcom library with the new ones with the following command :

WLIB CLIB3R-+IOB-+NFILES-+CMAIN386

The Watcom library modification is now complete.

The only other consideration is that DOS itself be allowed to use more than 20 files, which it also is set to by default. If this is not done, any changes to the C compiler library are useless. DOS is reconfigured via the command :

FILES=xxxx

in CONFIG.SYS, where 'xxxx' is the desired maximum number of open files to allow.

You are now ready to generate C sourcecode and do your first compilation.

See also:

Compiling - Generating C Sourcecode
Compiling under DOS - Compiling

03-11-95

Control Characters

View Topic

CONTROL CHARACTERS

Control characters can be included in a DISPLAY, PRINT or OUTPUT instruction.

The effect a control character has when included in an OUTPUT instruction depends on where you choose to send your output when the verb executes.

For some functions performed by the control characters you should use the equivalent standard verbs.

SCREEN CONTROL CHARACTERS

^J Moves cursor down one line in same column
^M Moves cursor to beginning of line, does not erase

^G Sounds tone

^E Turns on blinking
^F Turns off blinking

^H Moves cursor left one column, does not erase
^K Moves cursor to top left corner, does not erase
^L Clears screen and homes cursor

^N Turns on inverse video
^O Turns off inverse video

^P Turns on underlining
^Q Turns off underlining

^U Moves cursor right one column, does not erase

^X Turns on screen highlight
^Y Turns off screen highlight

^Z Moves cursor stright up one row, does not erase

PRINTER CONTROL CHARACTERS

Printer control characters should never be used in an application. Instead, define nouns called, for instance, BOLD ON, BOLD OFF and copy the corresponding control characters used by your printer into them.

If you want to use more than one printer type, the above way allows you to store your printer's control characters in a file and then change printer type from within your application. Therefore you also must not use the control character conversion of the PRAGMA description file.

^J Advances paper one line.
Corresponds to the down arrow key.

^L Form feed. Advances paper to top of new page.
Corresponds to the home key.

^M Prints contents of line (empties printer buffer)
and returns print head to left margin.

A "^M^J" is known as a line feed and is the standard way to advance the print head down one line.

The following printer control characters are outdated and may no longer apply to your printer. Consult your printer manual for more information.

^G Sounds printer bell in some printers.

^K Advances paper one vertical tab stop in some printers.

^N Turns on expanded print until a ^M or ^O is printed.
^O Turns off expanded print.

^R On some printers turns on condensed printing.
^T On some printers turns off condensed printing.

Converting - PFM Filenames

View Topic

CONVERTING FROM PRAGMA 3 TO PRAGMA 4 - PFM FILENAMES

During the conversion process from a PRAGMA 3 to a PRAGMA 4 program, file names need to be generated.

Each PRAGMA 4 file name must refer also to a .PFM file. DOS and UNIX have a restricted character set for use in file names, and a maximum length that is shorter than what PRAGMA allows. So here we must generate some sort of legal operating system name for each of the .PFM files. The maximum length of the .PFM file name is eight characters. Only the first eight characters of the PRAGMA file name are used. Counters are added to the name until a unique name is found, if necessary. This will be also the name of the .DES file that goes along with the .PFM file.

The program must, of course, find out if there is already a file by that name, and if there is, this name will be rejected, and the counter method comes in to play to find the next possible name. Each file must have a unique name in PRAGMA, and in the operating system.

For example, if we have two PRAGMA files called INVENTORY and INVENTORY XREF, the first one, alphabetically, (INVENTORY) will become INVENTOR, since that is the maximum eight characters. The files INVENTOR.DES and INVENTOR.PFM will be created (provided they do not exist already, which we will for this example assume). Later on, when the file INVENTORY XREF is being processed, it too will want to use the name INVENTOR. The program will look for INVENTOR.PFM and find it (it has already been used for the file INVENTORY). This name will be rejected and the next name, INVENTO1, will be tried. In this case, let's assume that it is accepted (because no file called INVENTO1.PFM currently exists). The program will then create a file called INVENTO1.DES and INVENTO1.PFM.

These names are called the "shortname" of the file. They are the names of the file in the operating system. The "longname" of the file is the complete PRAGMA name as it was.

When using PRA2PFM, if you have any .PFM files left over from a previous translation, this will cause the counters to be added unnecessarily. This is mentioned because it is sometimes desirable to retranslate an application and keep the data currently in the .PFM files without having to retransfer all of the file data again. When using PRA2PFM, it is done by having the .DES files present and using the NOXFER option. BUT NO .PFM files MUST BE PRESENT. If they are, the files this time around will have different names than they did last time (they will now have counters added to them). Thus, the newly translated program will NOT refer to the old .PFM files, but to the new ones with the counters added. This is because the shortname exists in the new file definition in PRVOCAB.PFM, and these are the names that are used when a .PFM file is searched for during runtime. Clearly, this is not what was intended, as we wanted the old files to match up to the newly translated program.

See also:

Converting From PRAGMA 3 - Basics
Converting From PRAGMA 3 Examples
Converting - The Online Program
Converting - The Program PRA2PFM
Converting - Standard Utility Verbs

Converting - Standard Utility Verbs

View Topic

CONVERTING FROM PRAGMA 3 TO PRAGMA 4 - STANDARD UTILITY VERBS

To maximize the convertibility to PRAGMA 4 of your PRAGMA 3 application you should use the suggested standard utility verbs in the PRAGMA 3 application that you want to convert. They are listed and explained in the PRAGMA version 3.63 System manual and the verbs for them are also supplied on the PRAGMA 3.63 release diskette.

The standard IPC verbs (Inter Process Communication, writing and reading to and from DOS) are substituted in PRAGMA 4 with direct calls to the operating system, thus eliminating the need to load the IPC modules into memory.

Likewise the standard screen management verbs are substituted in PRAGMA 4 with direct calls to the operating system. The use of standard screen utility verbs is the recommended way to address screens. By adhering to these specifications you maximize the portability of your application software. This is especially important if you want to run your applications under UNIX.

All of the PRAGMA 3 single control character commands are still supported. However, it is suggested when writing new software in PRAGMA 3 that these not be used and, instead, the standard utility verbs used in their place. Currently written software does not need to be changed to remove these control characters.

IPC STANDARD VERBS

The following is a list of the IPC standard verbs. A complete explanation is found in the PRAGMA 3.63 System manual. Be aware that the IPC standard verbs used in PRAGMA 3.63 have a dot preceding their name.

DOS CLOSE READ
DOS CLOSE WRITE
DOS COPY
DOS DELETE
DOS EXIST
DOS OPEN APPEND
DOS OPEN CREATE
DOS OPEN READ
DOS READ
DOS RENAME
DOS WRITE
GET IPC STATUS
IPC SERIAL

IPC STANDARD NOUNS

IPC STATUS

You obviously must use these utility verbs and nouns in your PRAGMA 3 applications, and must not use direct SEND and RECEIVE commands to communicate with IPC, because any SEND and RECEIVE commands will be passed over untouched during the conversion.

The IPC functions when converted perform their work by directly accessing operating system file calls; they DO NOT use SEND or RECEIVE. The SEND/RECEIVE terminator character settings remain the same. They continue to be used as termination characters for any reads or writes to or from DOS files.

Since no SEND or RECEIVE commands are actually used, it is possible to perform both normal serial I/O and IPC calls at the same time without having to perform IPC SERIAL calls to switch the flow. However, the IPC SERIAL procedure is provided simply so that you can replace the verb of the same name in PRAGMA 3 and not have to alter verbs. The IPC SERIAL actually does nothing except set IPC STATUS to "OK".

SCREEN STANDARD VERBS

The following is a list of the standard screen utility verbs that are automatically converted to equivalent standard verbs in PRAGMA 4. A complete explanation is found in the PRAGMA 3.63 System manual and in the PRAGMA 4 REFERENCE listing.

SET CURSOR POSITION
GET CURSOR POSITION

MOVE CURSOR LEFT
MOVE CURSOR RIGHT
MOVE CURSOR UP
MOVE CURSOR DOWN

CLEAR SCREEN
ERASE SCREEN

SET DISPLAY ATTRIBUTE

SET FOREGROUND COLOR
SET BACKGROUND COLOR

See also:

Converting From PRAGMA 3 - Basics
Converting From PRAGMA 3 Examples
Converting - The Online Program
Converting - The Program PRA2PFM
Converting - PFM Filenames

Converting - The Online Program

View Topic

CONVERTING FROM PRAGMA 3 TO PRAGMA 4 - USING THE ONLINE PROGRAM

Among the PRAGMA 4 online programs is one that lets you automatically convert a PRAGMA 3 program to a PRAGMA 4 with as little fuss as possible.

If your PRAGMA 3 program uses only internal files or internal files and Btrieve files, the online converting program is all you have to use. No manual intervention is necessary, provided your program follows the few rules described in the basics section for converting.

If your program uses the Fileserver you will have to manually transfer the data to the PFM format by writing simple verbs that transfer the data from the Fileserver to the empty PFM file that the conversion program automatically provides.

If your program uses Btrieve files and you wish to change to PFM files, you will also have to write simple verbs that transfer data from Btrieve files to an empty PFM file.

DOING THE CONVERSION

You can run a conversion only under DOS.

Make sure that your program follows the few rules and restrictions for converting, by making any necessary changes. Then selective save your application to get rid of unwanted verbs. Immediately before converting you MUST run a validation. Do not attempt to convert a program that has any errors.

Create an empty directory and copy the PRVOCAB.000, all the PRFILEXX.000 and the PRSYSTEM.XXX to the directory. You must use your version of PRSYSTEM.XXX since it contains your file access messages.

Copy to the directory the programs PRA2PFM.EXE and FILEUTIL.EXE. Also copy TERMINFO.LBS to the directory or make sure that it is in the directory \USR\LIB\TERMINFO. These programs are on the PRAGMA 4 DOS release diskette. Nothing else is needed, so make sure that nothing else is there to create confusion.

Run PRAGMA 4 from any other place, since you will be prompted for the name of the directory where you copied all the files.

Follow the menu choices of the online conversion. All the necessary explanations will be available. If you need more documentation on the conversion parameters or anything else, read all the sections on conversion that are available.

Once the conversion has terminated, copy the files PRMSG.PFM, PRSTD.PFM and PRAGMA.EXE and you can run your program under PRAGMA 4.

If you have to run the conversion more than once, make sure that you first delete all the files that were created by a previous conversion.

See also:

Converting From PRAGMA 3 - Basics
Converting From PRAGMA 3 Examples
Converting - Standard Utility Verbs
Converting - The Program PRA2PFM
Converting - PFM Filenames

Converting - The Program PRA2PFM

View Topic

THE CONVERSION PROGRAM PRA2PFM

The conversion program is called PRA2PFM. It converts user vocabulary from the PRAGMA 3 format into PRAGMA 4. To do so it reads user vocabulary from the PRVOCAB.000 file, reformats it, and writes it to the PRVOCAB.PFM file. It also performs the file transfer from internal files to PFM files.

There must be an empty PRVOCAB.PFM file present before invoking PRA2PFM. If you restart a conversion, you must begin with an empty PRVOCAB.PFM file. The converter does not create or empty this file. Below is a sample .DES file that can be used with FILEUTIL to create it. It is supplied in the DOS subdirectory of your PRAGMA release diskette.

PRVOCAB.DES

nouns=n
page=256
key=2
position=5
length=32
segment=n
position=1
length=1
segment=y
position=5
length=32
segment=n

The page size used is not critical, but 256 is a recommended minimum. The key positions and lengths ARE fixed at 5, 32 and 1, 1 respectively. Do not change these numbers.

When you invoke PRA2PFM you must supply certain parameters. The complete command line looks like this:

PRA2PFM INITFLAG XFERFLAG PROMPTFLAG SYSTEMNAME CONVERTDIRECTORY

The parameters have the following meanings:

INITFLAG

The initflag is either INIT or NOINIT, and it determines whether or not the noun values from user one in PRVOCAB.000 are copied. NOINIT is the default.

If NOINIT is chosen, every noun will have a value of numeric zero initially.

XFERFLAG

The xferflag is either XFER (transfer) or NOXFER (no transfer), and it determines whether internal file records are transferred into PFM files or not. NOXFER is the default.

The conversion program creates mock internal or mock external files.

The significant length of the reference is determined by the longest reference value of the corresponding internal file. If a significant length of a reference must be changed, you can use the prompt option to manually edit the significant length. Or you must have the already modified .DES file present during conversion time so that the conversion process will use the size information read from it when creating the file definition.

PROMPTFLAG

The promptflag tells PRA2PFM whether or not to ask the user to verify the guesses it has made for the size of the PFM unit and the significant length of the index for each file. The possible values are PROMPT, NOPROMPT and MAX. The default is NOPROMPT.

If MAX is chosen, PRA2PFM will use the total size of the LONGEST reference in the file as the significant length. An empty file will default to 16. This will result in a significant length that may be a bit larger than necessary in some cases, but it can be safer and is easier to use.

When PROMPT or NOPROMPT is specified, PRA2PFM attempts to find the SMALLEST possible significant length to use, by comparing all references in the file and using a size that is one more than the greatest duplication between any two references. These options attempt to save disk space. However, sometimes the significant lengths it calculates may be too small for future records.

If PROMPT is chosen, PRA2PFM will, during the processing of the files, show you the values it has generated by its guessing process. You may keep the current value by entering a zero. Otherwise enter another value if you do not like the value shown. These values will be then written to a .DES file, and the .PFM file will be generated from this. If a .DES currently exists, it will be used instead of going through the guessing process, and in that case you will also not be allowed to override these values, even if PROMPT is chosen. The only exception to this is if the existing .DES file has invalid data in it. In that case it will be ignored, PRA2PFM will make its best guess, and if PROMPT is chosen, you will have a chance to override this.

SYSTEMNAME

This is the name of the file containing the system messages. The EXTERNAL ECHO text is read from this file. The default name is PRSYSTEM.USA. If you use a different, translated PRSYSTEM you must use your own one, otherwise your application will not work.

CONVERT DIRECTORY

PRA2PFM has the ability to operate in a subdirectory, specified by this parameter. If this parameter is omitted, it will operate in the current directory. PRA2PFM expects to find all needed files in the working directory and will also create all of its output files in this directory.

A PRAGMA.DES file is created, which is the counterpart of the first user parameters found in the Setup System Parameters menu of PRAGMA 3.

A .PFM file is created for every file that a PRAGMA 3 application had defined, regardless of whether the file is found to be a real PRAGMA internal file, a Fileserver file, or a Btrieve file, and regardless of whether XFER or NOXFER is chosen. If these .PFM files are not needed, they can be deleted later.

Two sizes must be determined before the .PFM file can be created. The first is the significant length of the reference and the second is the unit size (page). If a .DES file already exists, it is read, and these two sizes are gotten from it. If the .DES file does not exist, and if NOXFER is chosen, a default of 16 for the key size and 128 for the unit size is used.

Otherwise (if XFER is chosen) the records in the file are inspected. The two sizes will be calculated based upon the records existing in the file at the time of conversion. The minimum possible unit size is 96. If the file is empty, the defaults above are used. Then, if the .DES file did not exist, it is created at this point with the values found by the procedure above.

If PROMPT is chosen you have the possibility to check and manually alter the calculated significant length of the reference and unit size.

Note that the significant length of a reference exists in the .DES file and the .PFM file. This size is only important for mock internal, mock external files and native PFM files. True Btrieve files do not need this key size information. If you wish to change this size after converting, you can change it in the file definition in the PRVOCAB.PFM and then redefine the empty file.

Next, the .DES file is used to create a .PFM file. This again will happen regardless of whether XFER or NOXFER is chosen. Be careful if you are using NOXFER and want to save the file data already in .PFM files. If the old .PFM files are present, they will be overwritten with the new .PFM files being created. Keep them in another directory.

Lastly, only if XFER is chosen, the file records are transferred. Every internal file with records in it will be transferred.

Even if the NOXFER parameter is used, the .DES files will still be searched for, and if found, their significant length of reference information used. Again, this is because the significant length of the reference must be placed into the .PFM file, which it is currently creating.

All of this can help you when you must reconvert your program, but you want to keep the file data that is already in PFM files. This file data may have been put there by a previous conversion, or by running the program with the new interpreter. If the PFM file is "mock internal" or "mock external", the significant length of the reference is important. What is actually used in the PFM file and what is specified in the .DES file must be identical. It is now possible to ensure this automatically. If you want to reconvert and keep all PFM file data without re transferring it all over again, simply use the NOXFER parameter to PRA2PFM and make sure that all of the old .DES files ARE present for PRA2PFM to inspect during conversion time. Make sure that the .PFM files ARE NOT present however, or they will be overwritten with the new .PFM files that converter creates. If a .DES file is found, it WILL use the significant length of reference gotten from the .DES files in the .PFM files. Thus, all of these different places where the significant length of reference is referred to will be in agreement. If the PFM files are NOT mock internal or mock external, the .DES files do not have to be present. PRA2PFM will then use 16 as the default, and so the created .DES file is not used in this case anyway.

WARNING. When converting from PRAGMA 3 to PRAGMA 4 more than one time, make sure that the significant references are the same for the same file. Otherwise if you access a file from two vocabs that have different significant reference length, you corrupt the file.

THE PRA2PFM.LOG FILE

During the conversion a log file called PRA2PFM.LOG is created. This file is created or appended to in the working directory. All errors or other special situations are displayed to the screen and logged to this file. Each log session has a timestamp and a header.

WARNING. When performing a conversion make sure that the DOS command APPEND is NOT available. APPEND might redirect the output of the conversion program to directories that contain valuable data.

Converting ADAM Applications

View Topic

ADAM TO PRAGMA 4 CONVERSION

To convert an old ADAM program to PRAGMA 4 you must first convert the ADAM program to NL or to PRAGMA 3.

Once you have converted your program to NL or PRAGMA 3 you can continue with the conversion to PRAGMA 4 as described in another entry of the extended online help.

Whether you convert from ADAM to NL or to PRAGMA 3 depends on what programs you have available. All being equal you should convert to the latest version of PRAGMA 3.

If your ADAM system has been translated to a foreign language and the data is still stored in the 7 bit format, customized to your country, you must use a translation table when importing your data from the Fileserver to PFM or Btrieve files. The translation table will convert the 7 bit format to the IBM character set. For further details please consult the entry from Goliath to PRAGMA 4 Conversion

ADAM TO NL CONVERSION

To connect the two machines you need the following cable:

ADAM NL
2 ---------------- 3
3 ---------------- 2
7 ---------------- 7
5 ---------------- 4
4 ---------------- 5
6 ---- ---- 6
| |
20 --- ---- 20

On the ADAM side connect the cable to port #9.
Set the baud rate for that port to 9600 baud, no parity and 8 bits.
Set the SEND/RECEIVE parameters to none,^@.

Make sure that the vocab validates correctly.

On the PC prepare an empty copy of NL. You may have to connect the serial cable and the serial security device to the same communications port, COM1.

Before loading NL, load the memory resident programs AUXIN.COM and NL2LXTUS.COM.

NL2LXTUS.COM is used if you are using NLSYSTEM.USA. For other countries you must use the correct version of NL2LXT. In Germany for instance, you must use NL2LXTD.COM.

Set the baud rate like on the ADAM. The SEND/RECEIVE parameters to none, ^@ and none.

Enter the extended utilities with the password <CONTROL-BREAK> PUNK.

Choose the conversion option ADAM/DAVID/TINA --> L-XT

The PC will go to the Start prompt and is ready to recive from the Adam.

On the ADAM enter the utilities and choose the ADAM --> TINA/DAVID conversion option.

During the transfer the ADAM machine will list the verbs that are being sent to the PC.
The NL machine will show each line of the verb it is receiving.

When the conversion has been completd run a validation and check that your program runs correctly before continuing the conversion to PRAGMA 4.

POSSIBLE PROBLEMS

If the ADAM vocab contains an object verb in which the object has been cancelled, the conversion will abort. Write down the verb name with the missing object, correct the problem and start the conversion again.

See also:

Converting NL Applications
Converting from PRAGMA 3 - Basics
Converting from PRAGMA 3 - Examples
Goliath to PRAGMA 4 Conversion

Converting From PRAGMA 3 - Basics

View Topic

CONVERTING FROM PRAGMA 3 - BASICS

We provide you with an as easy as possible conversion path for your PRAGMA 3 applications. But in order to be able to convert your application you must use PRAGMA version 3.63 or any later versions. If you are running earlier versions of PRAGMA, you must first upgrade to PRAGMA 3.63 and make sure your application validates and runs correctly with that version. Instructions on how to upgrade old applications to PRAGMA 3.63 can be found in the System manual of PRAGMA 3.63. Old NL applications can be converted directly to PRAGMA 4. The instructions on how to do it can be found in the CONVERTING NL APPLICATIONS section.

The most frequent types of applications that will be converted to PRAGMA 4 will fall into one of these categories.

1 Applications using exclusively PRAGMA's internal files with the internal file commands, like GET, SAVE, etc. All the data resides in the internal files. The conversion is completely automatic and all the data can be automatically ported over to the new file format.

2 Applications using PRAGMA's internal files with the internal files commands (GET, SAVE, etc.) and using the external file commands (EXTERNAL GET, EXTERNAL SAVE, etc.) with the Fileserver. The data that resides in the internal files can be automatically ported over to the new file format. The Fileserver data has to be transferred to the new file format by writing a simple verb that transfers the data from the Fileserver to an empty PFM file that the conversion program automatically provides.

3 Applications using PRAGMA's internal files with the internal file commands (GET, SAVE, etc.) and using the external files commands (EXTERNAL GET, EXTERNAL SAVE etc.) with Btrieve. The data that resides in the internal files can be automatically ported over to the new file format. The Btrieve data can remain in Btrieve files since PRAGMA can access Btrieve files.

4 Applications using Btrieve files, to be changed to PFM files. You may have to abandon Btrieve files if you plan to run your application under a UNIX that does not support Btrieve. You will have to write a simple verb that transfers the data from Btrieve files to an empty PFM file.

RULES AND RESTRICTIONS FOR CONVERTING

PRAGMA 3 applications can easily be converted to PRAGMA 4 provided a few simple rules are met.

IPC COMMANDS

Your IPC COMMANDS must be used with the standard utility verbs that are explained in the PRAGMA 3 System manual. Only then will they be automatically converted to the new standard verbs.

INPUT 0

If you use INPUT 0 in your application and you plan to run your converted application under UNIX, you probably will have to manually change many occurrences of INPUT 0 with the new standard verb INPUT KEY, to minimize waste of CPU time in a multi-user system. Consult the PRAGMA 4 online REFERENCE for further details on INPUT 0.

FILE POINTERS

You are not allowed to use the same name for a file that is used for internal files and external files. Before or after the conversion you must rename one of the files. PRAGMA 4 does not allow a file pointer between internal and external files to be shared.

FILESERVER

You can access PRAGMA's Fileserver from DOS, using the DOS version of PRAGMA 4, or from UNIX.

You are not anymore allowed to use the verb EXTERNAL TIME. Trace it and substitute it with the verb PUT TIME.

MISSING LABELS

If your program has a GOTO without its corresponding LABEL, the converting program will automatically add the missing label to the end of the verb definition. It will also display the missing label information on the screen. Beware that adding the missing label will enable the upgrade program to upgrade your program, but the program logic will more than likely not be what it should. You will have to manually insert the label into the correct place in the verb definition.

MISSING OBJECTS

Missing objects are inserted, using the actual standard noun called OBJECT, which is not used in any other situation. Unnecessary objects are discarded.

NOUN VALUES

Noun values can be written back to the PRVOCAB at execution end. To enable this feature you must have the statement WRITE NOUNS = YES in the PRAGMA description file. But you cannot use this feature when more than one user has to access the VOCAB, like under UNIX. So it is NOT a good idea to use nouns to store data.

Standard noun values are NEVER written back to disk. They exist only in memory and all values are lost when you return to the operating system.

You cannot put the terminal number into a noun since PRAGMA 4 does not have multiple noun value slots like PRAGMA 3. If you must differentiate between users under UNIX, have each user who logs on read a numeric file, increment by one the last number found and then use the new number for himself.

NUMERIC REFERENCES

PFM fully supports numeric references. But you must have a statement saying PFM NUMERIC REFS = YES in the PRAGMA description file.

Btrieve only supports numeric references when they are converted to strings. To do this you can JOIN your REFERENCE in front of "^@". If the key is fractional, you need to come up with some other indexing scheme for this file that does not need fractional numeric keys because they are not supported. Also note that these numeric keys will not sort in numeric order once they are in the Btrieve file (you will get 1, 10, 11, 2, 3, 4, etc.) because Btrieve always uses ASCII string references. If you want them in numerical order it is best to pad them, rather than simply make them into strings.

SECURITY CODE CHARACTERS

The four security codes (CTRL \, CTRL], CTRL^, CTRL^) are no longer supported. During the conversion process PRA2PFM automatically removes them and they are substituted with a question mark (character "?"). In the unlikely event that this may cause you to have duplicate names, you will have to RENAME one of the duplicate names and start the conversion again. For instance, if you named four verbs with names consisting only of the four security codes, duplicate names will be created during the conversion process. For some strange reason the error message will say "PRVOCAB.PFM is missing".

SECURED APPLICATIONS

You cannot convert an application that has been secured to a special block. If the conversion program PRA2PFM finds a secured application, it will abort.

UNSUPPORTED VERBS

The following verbs could be used in a verb definition in PRAGMA 3. In PRAGMA 4 they can only be used interactively, that is from the START message. During the conversion they are transformed into COMMENTs, and the original verb line becomes the text of the comment.

RECAP (RC) RECAP ALL (RA) STATUS (SS)

VALIDATION

Immediately before converting an application you MUST run a validation. You can only convert applications that pass the validation check WITHOUT ANY errors. A conversion of a corrupted application can destroy all the data on your hard disk! You have been warned.

Converting From PRAGMA 3 - Examples

View Topic

CONVERTING EXAMPLES

The actual conversion is done under DOS, regardless of what operating system you plan to use.

After having made sure that your application conforms to the rules on converting, copy the PRVOCAB.000, PRFILEXX.000 and PRSYSTEM.XXX to an empty subdirectory. Make sure that you use your own version of PRSYSTEM.XXX if you did not use the original version of PRSYSTEM.XXX with PRAGMA 3.

If necessary alter the AUTOEXEC verb and then selectively save your application to get rid of unwanted verbs. As a last check run a validation. Only applications that validate without errors can be successfully converted! This simple step can save you a lot of grief later. Don't simply assume that everything is OK.

Copy to that directory PRA2PFM.EXE, and an empty PRVOCAB.PFM file. Make sure that no other .PFM or .DES files are present at this moment.

Most of the applications to be upgraded will use PRAGMA's internal files with the internal files commands (GET, SAVE etc.). The external files commands (EXTERNAL GET, EXTERNAL SAVE etc.) will either address PRAGMA's FILESERVER or the Btrieve filemanager. Also most applications do not initialize their nouns but rely on PRAGMA to remember the noun values. Therefore during the conversion you will want to carry over the values of the nouns and all the data from your internal files. The PRA2PFM command line will then look like this:

PRA2PFM INIT XFER NOPROMPT PRSYSTEM.USA CONVERTDIRECTORY

CONVERTDIRECTORY is an optional parameter that lets you start the conversion program from another directory.

When you start PRA2PFM with that command line, the following things will happen:

The empty PRVOCAB.PFM will be filled with the application vocabulary taken from PRVOCAB.000.

A PRAGMA.DES file will be created that contains the necessary parameters for your program to run. The parameters will reflect the settings that you had in the PRAGMA 3 setup for the first user.

For every file that a PRAGMA 3 application defined, regardless whether it was used with internal file commands or external file commands, a FILENAME.DES and a FILENAME.PFM are created. And having used the XFER option, all the data of the files that were used with the internal file commands are transferred to the FILENAME.PFM. This automatic data conversion creates mock internal PFM files. That is, they behave and have all the characteristics of the PRAGMA 3 internal files.

Some finishing touches may be necessary, depending on the type of application you have.

APPLICATION USING PRAGMA'S INTERNAL FILES EXCLUSIVELY

In most cases, you will have finished. You are ready to run your PRAGMA 3 application under PRAGMA 4.

The only problem that you may encounter is one having to do with the significant length of the references.

During conversion, the significant length of the reference for each file must be determined. If the file has no records in it, the significant length of the reference will default to 16. Otherwise, you have the choice of how the significant length is determined.

If you choose PROMPT or NOPROMPT for the promptflag, every file record is read and the significant length of the reference of the file will be one greater than the maximum number of characters there were seen to be duplicated between any two file records in the file. For numeric references, it will be eight.

For a file where the references are generally stable, this is not a problem, as it will produce the smallest possible significant length of the reference that will work for this file. But for a file where the references are quite variable, this may cause a problem. The significant length of the reference automatically chosen may be too small for the file. It is chosen based upon the records that exist in the file at the time of conversion; records placed in the file later may need a bigger significant length of reference. The significant length of the reference will be the first so many characters of the first noun. The first field is variable-length, but the significant length of the reference is always fixed-length. A good example of a place where this automatic significant length of the reference determination can run into problems is a file where the reference is a person's name. Let's say for example that there were some records in the file, and the conversion routine determined that the significant length of the reference for the file should be eight. It looked through every record in the file and it found a maximum of seven characters of duplication between any two records in the file. Later, two records are added to the file that have greater duplication, like "Josephson, Allen", and "Josephson, Mary". These records have 11 characters of duplication. Since the significant length of the reference for the file is eight, only the first eight bytes are compared. The file manager will then return a duplicate reference status.

To get around this, you will have to override this automatic significant length of the reference determination. You can do this by having a .DES file present that contains the significant length of the reference you desire. An easy way to build these is to simply let the converter transfer all of the records and build all of the .DES files. Then, edit any .DES files whose significant length of the reference is unsatisfactory, delete all PFM files and retranslate.

When editing a .DES file, be certain that the unit size is large enough.

Another way to override the automatic significant length of the reference determination is to use the PROMPT option in the PRA2PFM command line. You can then verify the size of the PFM unit and the significant length of the reference of each file.

If you choose the option MAX, the total size of the longest reference in the file will be used as the significant length. This will produce larger files and diminish the problems described above, but in extreme cases not eliminate them. You may then proceed as described above.

The PFM file manager can perform record locking as part of its mock internal file emulation. This automatic record locking can be disabled if so desired. (Remember that PRAGMA 3's automatic record locking is limited to lock one record per user, NOT per file, one record total).

The PRAGMA 3 internal files have built-in testing of file statuses. An "end of file" situation on a GET NEXT, for instance, produces a RETURN out of a verb. A "record not found" situation causes an abort. When you use PFM files emulating the internal PRAGMA files this characteristic is kept. Thus, to ensure a proper flow control within the program, if a "record not found" statement is encountered, it will cause a return from the verb. Any other bad statuses cause an abort, equivalent to a "return to start" in PRAGMA 3.

APPLICATION USING PRAGMA' S INTERNAL FILES AND FILESERVER

If you want to go on accessing the Fileserver the only thing left to do is to delete the .DES and empty .PFM files that relate to the Fileserver.

But remember that you can access the Fileserver only from PRAGMA DOS and from UNIX.

If you are porting an application that runs with the Fileserver to OS/2 or a network, you will have to take the data from the Fileserver and transfer it to .PFM files in mock external file emulation. The PRAGMA program will then use PFM in conjunction with the EXTERNAL file commands and mock external file emulation.

1 In your PRAGMA 4 application you must not access the same file with the internal and external file verbs. If you use the SAME file in PRAGMA 3 for both internal use and Fileserver use, and in PRAGMA 4 you use PFM or Btrieve for both files, you must alter the verbs to give the external file a different name than the internal file. This is because the file pointer is shared for the internal and external file verbs.

2 In PRAGMA 3 transfer all the Fileserver file records into PRAGMA internal files. You DO NOT have to change your program logic to use internal files, only the records themselves must be moved from Fileserver to internal files. Write small verbs to do this transfer, and then FORGET them or SELECTIVE SAVE them after you are done. Should any Fileserver file not fit into the internal files, write its name down and don't worry about it at this point.

3 Do your conversion, using the XFER parameter to PRA2PFM. The .DES and .PFM files will be created and the file records will be transferred from the internal files to the .PFM files. The proper significant length of the reference will be calculated, etc.

4 The .DES and empty .PFM files will be created for Fileserver files that are too big. Since the internal file was empty, and since no .DES file existed, the default significant length of the reference of 16 was used during upgrade. This may not meet your needs. If not, you must decide upon a significant length of the reference for this file. The .DES files must then be edited to contain this size and FILEUTIL -CREATE must be run to create the proper empty .PFM file.

5 Rename the so created empty .PFM file. As an example, if the original file is called TEST.PFM call it TESTX.PFM.

6 In the newly created PRAGMA 4 vocab define a new file called TESTX. It must use exactly the same nouns as the already defined file TEST. It must also be a mock fileserver file like TEST (mock flag 2). Make sure that both file headers are the same in this regard.

7 Write a verb that uses EXTERNAL GET to read all the data from the Fileserver file (TEST) and uses SAVE to write the data to the newly created TESTX file. In the PRAGMA.DES file you must use PFM as internal file manager and Fileserver as external file manager.

8 After having run the transferring verb make sure that the file TESTX .PFM has been properly filled. You can check that with the verb LIST REFERENCE and EXTERNAL LIST REFERENCE. Go back to DOS and RENAME TESTX.PFM to TEST.PFM. In PRAGMA 4 you can FORGET the transferring verb and the file TESTX.

9 In PRAGMA 4 check if you are using the verb EXTERNAL TIME. If you do, exchange it for the verb PUT TIME. If you used EXTERNAL TIME only to check the connection between PRAGMA 3 and the FILESERVER, you can delete that part of the verb, since it is no longer necessary.

10 Change the external file manager from Fileserver to PFM. Your application will now work with PFM the same way that it worked for Fileserver without additional changes.

The PFM file manager can perform the Fileserver automatic record locking as part of its external file emulation. This feature is enabled or disabled in the parameter description file created by the translator. Remember that the PRAGMA automatic record locking limits the locking to one record per user (NOT per file, one record total).

APPLICATION USING PRAGMA'S INTERNAL FILES AND BTRIEVE

In most cases you will want to go on using Btrieve as your filemanager, and if so, you only need to delete the extra .DES and .PFM files that relate to Btrieve. PRAGMA 4 will access your Btrieve files.

The only problem that you might encounter is if you used hyphens in the Btrieve filenames. You will have to rename them to match the shortname in the PRAGMA file definition.

Btrieve is not supported in UNIX. After all, Btrieve belongs to Novell, the network people, who don't care much about UNIX.

To port your data that resides in Btrieve files to PFM you will have to proceed in the following way.

1 Let's assume that PFM is chosen as the internal file manager and Btrieve as the external one. Let's call the Btrieve file TEST.BTR and the PRAGMA file TEST.

2 Manually edit the Btrieve description file TEST.DES to make it a PFM.DES file and rename it to TESTX.DES. Use FILEUTIL -CREATE to create the empty TESTX.PFM file. This procedure is explained under FILEUTIL in the Utilities section of this manual. (Remember that you have to invert the page and key description.)

3 In PRAGMA define a new file called TESTX. It must use exactly the same nouns as the already defined file TEST.

4 Write a verb that uses EXTERNAL GET to read your Btrieve file and then uses SAVE to write the data to the newly created TESTX file. This verb must be written assuming a Btrieve file style (checking EXTERNAL ECHO, etc., for both internal and external operations).

5 After having run the transferring verb make sure that the file TESTX .PFM has been properly filled. You can check that with the verb LIST REFERENCE and EXTERNAL LIST REFERENCE. Go back to DOS and RENAME TESTX.PFM to become TEST.PFM. In PRAGMA you can FORGET the transferring verb and the file TESTX.

6 Change the external file manager from Btrieve to PFM. Your application will now work with PFM the same way that it worked for Btrieve without additional changes.

See also:

Converting From PRAGMA 3 - Basics
Converting - Standard Utility Verbs
Converting - The Online Program
Converting - The Program PRA2PFM
Converting - PFM Filenames

Converting NL Applications

View Topic

Cut, Copy, Move and Paste

View Topic

Cut, Copy, Move and Paste

You can select a portion of the screen and cut it, move it or copy it to the clipboard and from there insert it again anywhere on the screen or on a different screen.

To CUT position the cursor at the place where you want to start the cut and then hit the <DEL> key. Then position the cursor where you want to end the cut and hit the <RETURN/ENTER> key. The piece of erased screen will be put into the clipboard.

To COPY position the cursor at the place where you want to start to copy and then hit the <ALT-C> key. Then position the cursor where you want to end to copy and hit the <RETURN/ENTER> key. The piece of copied screen will be put into the clipboard.

To PASTE from the clipboard position the cursor at the place where you want to start the insertion and hit the <INS> key. The piece of screen contained in the clipboard will be displayed on the screen, in the original colors. You can also paste from the clipboard with the <ALT-P> key. The piece of screen contained in the clipboard will be displayed on the screen with the attribute and colors that are active at the moment of pasting.

To MOVE position the cursor at the place where you want to start the portion of screen that you want to move and then hit the <ALT-M> key. Then position the cursor where you want to end the portion of the screen that you want to move and hit the <RETURN/ENTER> key. You wll be able to move the piece of chosen screen with the <UP>, <DOWN>, <RIGHT> and <LEFT> arrow keys. When your object is in the right place, hit <RETURN/ENTER>. Should you change your mind, hit the <ESC> key.

You can insert the contents of the clipboard onto a different screen, if you wish, since the contents of the clipboard are preserved until you exit the PRSCR program.

If you hit the <F6>-key a window will be opened that displays various graphic symbols. The <SHIFT-F6> key will open a window with various alphabetical symbols. With the arrow keys move the highlight to a symbol and hit <RETURN/ENTER>. The chosen character will be put into the clipboard. From the clipboard it can be inserted anywhere on the edit screen with the <INS> or <ALT-P> keys.

DOS 88 Memory Management

View Topic

PRAGMA DOS88 AND MEMORY

To be able to run the PRAGMA DOS88 version you must ensure the following conditions are met.

BASE MEMORY

It is very important that you have as much base memory available as possible. The base memory of DOS is 640 K. Eliminate any utility or memory resident program that is not used while running PRAGMA. The more memory that is available, the better your chance that your program will not run out of memory. For this reason, DOS 5.0 is the best version of DOS to use for PRAGMA DOS88. In this version, DOS itself and many other programs, like network shells, etc., may be loaded into high memory. In the best case you should be able to keep about 620 K free for PRAGMA. Every little bit counts.

WRITE NOUNS

You must enable the writeback of nouns to disk by putting a WRITE NOUNS = YES statement into PRAGMA.DES.

CLOSE ALL FILES

The PRAGMA memory manager can only discard closed files and nouns that are not used by any open files. Place at strategic places throughout your program, as often as possible, the verb CLOSE ALL FILES. The beginning of a menu is a good place, for instance. But do not CLOSE ALL FILES at random places. CLOSE ALL FILES takes some time, for one thing, and the THIS pointer for the file is also lost at the time the file is closed. Only close files when you are sure you don't need the THIS pointer any longer.

RUNNING THE APPLICATION

Do not use ALTER or access the on-line help before running a big application. The memory management of these parts has not been optimized. If you do any altering, simply go back to DOS before starting the application.

HOW THE MEMORY MANAGEMENT WORKS

The swapping is now composed of four passes, or phases. When memory is exhausted, the swapping always starts at pass one. If enough memory is freed with this, the swapping ends and is happy. Otherwise, successively deeper passes are executed. If all four passes cannot free enough memory, the system bails out to the operating system.

The first pass is to discard all verbs EXCEPT the current verb in use.

The second pass is to discard all files that are closed AND are not used in the current verb. If a file was at one time used in the current verb, even if it was closed, it will NOT be discarded.

The third pass is to discard all nouns that are not used in the current verb AND are not used in any of the files that still remain. This pass, in order to be most effective, requires that WRITE NOUNS = YES be used in PRAGMA.DES.

The fourth pass is to discard any CLOSED files that were at one time in use by the current verb, and also to discard all nouns values that belong to the file definition of all open files, with two exceptions. Neither the items that exist in the current definition line nor, if you are currently executing a definition line that accesses a file, the nouns of that file definition are discarded. Obviously, PRAGMA must run SOMETHING. You cannot throw out the line of definition that is currently being executed.

When referring to a verb or file definition, we mean only the verb or file definition themselves, and specifically exclude the items used in that definition. In other words, if the verb A uses the noun B, when we say that the verb definition of A is still in memory, it does not necessarily mean that the noun B is also loaded in memory.

At the end of all four passes, ONLY the following items will remain loaded in memory:

the current verb definition,
any nouns or files used in the current definition line of the current verb,
any open file definitions, and
if noun value writeback is disabled, ALL modified nouns MUST remain in memory.

If you disable noun value writeback, you will seriously hinder the efforts of the memory manager. Further, if you never CLOSE ALL FILES, you will also hinder the memory manager by unnecessarily wasting precious memory with files and nouns that are not being used at the moment. Open files, and especially the nouns that comprise their definitions, are the major users of memory. Performing a CLOSE ALL FILES as often as possible is necessary to keep memory usage to a minimum.

Debugger

View Topic

THE DEBUGGER

To enter the debugger, you type the standard word DEBUG (DB) at the START message.

You then get the debugger command window with the debugger prompt (similar to the START message, except it says "DEBUG").

To toggle between the two windows of the debugger, when the second window is present, hit the <F4> key.

To exit the debugger and return to START, simply press <RETURN/ENTER> at the debug prompt without typing any command. The verb ABORT EXECUTION (AEX) will accomplish the same thing.

The following debugger commands are available:

ABORT EXECUTION (AEX)
EDIT NOUN VALUE (ENV)
LOAD VERB (LDV)
RUN VERB (RUN)
SET BREAKPOINT (BP)
SHOW VERB STACK (SVS)
REMOVE BREAKPOINT (RBP)
VIEW PROGRAM SCREEN (VPS)

In addition to the above commands, some of the commands normally available from START are also usable under debug. These are:

ALTER (AL)
DISPLAY (DS)
LIST FILES (LF)
LIST NOUNS (LN)
LIST STANDARDS (LS)
LIST VERBS (LV)
RECAP (RC)
RECAP ALL (RA)
TRACE (TR)

DISPLAY (DS) You can look at the value of any noun by DISPLAYing it. The value will be displayed in definition form (i.e., strings are bounded by double quote characters and control characters are changed into underline sequences).

EDIT NOUN VALUE (ENV) lets you change any noun value. The new value will be written back to the disk only if you have the statement WRITE NOUNS = YES in the PRAGMA.DES file.

Before you can do much of anything, you must load the verb that you wish to run and debug. You use LOAD VERB (LDV)to do this. It asks for the name of the verb. It simply prepares this verb to be run and debugged, and then returns to the debug prompt.

To begin execution of the verb you have just loaded type RUN VERB (RUN). If at any time you interrupt a running verb by pressing <CONTROL-C> twice, this verb is suspended, and you return to the debug prompt. If you use RUN VERB (RUN) again, you will pick up where you left off. If you want to run the verb from the beginning, you must LOAD VERB again. LOAD VERB will terminate the running of the current verb, if any, before loading in the new verb.

Whenever you interrupt a running verb, you may SHOW VERB STACK (SVS) to display the verb stack.

The debugger will maintain separate screen images for the debugger output and your program output. When you RUN VERB, the debugger screen is saved, the program screen is restored, and then your program is started or resumed. When your program terminates, when you interrupt it with <CONTROL-C>, or when you hit a breakpoint, the program screen is saved, the debugger screen is restored, and then you go to the debug prompt. If you wish to see the program screen without having to resume the program with RUN VERB, you may use VIEW PROGRAM SCREEN (VPS). This command will save the debugger screen, show you the program screen, and wait for you to press a key. When you press a key, the debugger screen is restored, and you return to the debug prompt.

SET BREAKPOINT (BP) You can currently only set breakpoints at the beginning of a verb. SET BREAKPOINT asks for the name of the verb. You cannot set a breakpoint until you have first loaded a verb with LOAD VERB (LDV). When executing, if you come upon a verb where there is a breakpoint set, execution is suspended, and the debug prompt is returned to. You may examine nouns, etc., and then resume execution with RUN VERB. The breakpoints stay put until removed.

REMOVE BREAKPOINT (RBP) To remove a breakpoint, you use REMOVE BREAKPOINT (RBP).

Another way to enter the debugger is to interrupt the execution of a program by hitting <CONTROL-C> twice. Sometimes you must also hit <RETURN/ENTER> after the <CONTROL-C>'s. This will also get you into the debugger.

To exit the debugger you simply hit <RETURN/ENTER> and the program will resume from where it stopped. Or enter the command ABORT EXECUTION (AEX) to return to the START prompt.

DEBUGGER ON UNIX TERMINALS

Serial UNIX terminals do not support windowing, and therefore the debugger should only be used in full screen mode when using terminals.

To operate in full screen mode there must be the statement EDITOR FULL SCREEN = YES in the PRAGMA description file.

To keep the speed of a terminal acceptable you should use terminals that support scrolling up and down and insert and delete line. If the terminal has these capacities, they must be specified in the file TERMINFO.LBS. In other words, the smarter the terminal, the better the performance.

A mathematical coprocessor will also greatly enhance the speed of the UNIX terminals, since UNIX is very slow without a math coprocessor.

See also:

Error Handling

Debugging - Advanced Options

View Topic

ADVANCED DEBUGGING

STARTUP PROBLEMS

Should the DOS version of PRAGMA have any problems during startup (before the START message is displayed), you can SET the following argument in the environment:

SET P4DB=PROGRESS

PRAGMA will then display some messages showing the progress of the initialization. To proceed, any key can be pressed after each message. After the START message has been reached, no more messages will occur.

Be aware that the message informing you that PRAGMA.DES is being read is repeated many times.

This feature has been enabled with version 4.21.01

To turn this feature off do a SET P4DB=;.

STARTUP PROBLEMS WITH WINDOWS

Should the DOS version of PRAGMA have any problems during startup under Windows put the file WEMU387.386 into the directory \WINDOWS\SYSTEM and to your SYSTEM.INI in the [386Enh] section, add the following line:

device=\WINDOWS\SYSTEM\WEMU387

NUMERIC VALUE CRASH UNDER WINDOWS

Should you get a numeric value crash when starting PRAGMA under Windows first make sure that you have added the file WEMU387.386 to your \WINDOWS\SYSTEM (see above).

Should the problem persist SET the following argument in the environment:

SET P4DB=NUMERRDEBUG

PRAGMA will then display descriptive error messages when an invalid numeric error happens. Print the screen and fax it to Logical Business Systems.

MEMORY MANAGEMENT

To get a better feeling of how the DOS 8088 version of PRAGMA 4 manages memory, you can SET the following arguments in the environment:

SET P4DB=REORG;

PRAGMA will then beep once for each phase of the memory swapping routine. The first beep is when verbs are being discarded, the second when files are being discarded and third when nouns are being discarded. Sometimes there will be only one or two beeps, if that frees sufficient memory. When there are three beeps, everything possible is going out, and there will be a delay when nouns are written back to disk.

SET P4DB=REORG;MEMFREE;HEAPSHOW;

In addition to beep it will tell PRAGMA, to show the memory pool, so that you can see what is free and what is used. This will happen when exiting to DOS or when memory allocation fails, because memory reorganization cannot produce enough free memory.

Usually there should not be any used blocks when exiting normally. An exeption is if the on-line help has been used.

To list all the blocks hold down the SPACE key. Hitting RETURN will terminate the block display.

A final parameter is HEAPDEBUG. This causes PRAGMA to verify the memory pool after every allocation or resize request. This is used to track bugs that destroy the memory pool. If this option is used, everything will be tracked and it will make everything EXTREMELY slow., so use it only if there is a bug that causes the machine to hang or crash. It helps you to pinpoint which instruction is blowing things up. Or, in any event, you can use it to determine if the hanging or crashing is a result of the memory pool being trashed or not. If the pool is messed up, the entire pool will be shown and the program will terminate.

The parameter DUMPALL forces the memory reorganization to perform a complete run through all four passes every time it acts. The memory reorganization behaves differently with DUMPALL. Possibly there is less fragmentation.

To turn this feature off do a SET P4DB=;

Definition Editor

View Topic

THE PRAGMA DEFINITION EDITOR

AT THE START MESSAGE

RETURN KEY Terminates PRAGMA and returns you to the operating system
prompt.

F1 KEY Accesses the online help and reference program.

<F5> Redirects the output of all the standard interactive-only
verbs that produce an output of some sort to the SCREEN.

<F6> Redirects the output of all the standard interactive-only
verbs that produce an output of some sort to the PRINTER
device or a file, depending on how the PRINTER parameter
in the PRAGMA description file has been set.

<F7> Redirects the output of all the standard interactive-only
verbs that produce an output of some sort to the
COMMUNICATIONS device or file, depending on how the
PRINTER parameter in the PRAGMA description file has been
set.

<F8> Redirects the output of all the standard interactive-only
verbs that produce an output of some sort to the
PRAGMA.LOG file.

At the START message you can run, create or alter user-defined verbs.
You may also run the interactive-only verbs.
The debugger can also be accessed from the START message.

Interactive-only verbs are verbs that cannot be included into the definition of a verb and perform such tasks as listing, merging, creating, altering and forgetting verbs.

You cannot run a standard verb or a user-defined object verb from the START message. These must be part of a user-defined verb to run.

To run a user-defined verb or an interactive-only verb you simply type its name and then hit <RETURN/ENTER>. PRAGMA will run the verb and go back to the START message at its completion.

Be aware that PRAGMA is case sensitive, that is, you must type the name of the verbs exactly the way they have been written. Unless you have the statement LOWER TO UPPER CASE = YES in the PRAGMA description file, in which case only upper case characters are allowed.

All the keys are remappable in the PRAGMA description file.

ALTERING A VERB

RETURN KEY Terminates altering and displays the exit prompt. If you
hit <RETURN/ENTER> again you go to the name prompt, then hitting
<RETURN/ENTER> again you go back to the START message and all
the changes made to the verb or file are saved.

When inserting a new line or editing a line accepts the
field that was entered.

TAB KEY Edits an existing line. The line below the cursor will
be re displayed as you tab through it, letting you edit
the fields or leave them as they are.

ARROW DOWN KEY Moves the cursor or the insertion space down one line.

ARROW UP KEY Moves the cursor or the insertion space up one line.
If the cursor is on line one, moves the cursor to the top
of the verb header.

PAGE DOWN KEY Moves the cursor or the insertion space down one
screenful.

PAGE UP KEY Moves the cursor or the insertion space up one screenful.
If the cursor is on line one, moves the cursor to the top
of the verb header.

CONTROL-PAGE Moves the cursor or the insertion space to the end of the
DOWN KEY verb definition.

CONTROL-PAGE Moves the cursor or the insertion space to the beginning
UP KEY of the verb definition.

F1 KEY Accesses the on-line help and reference program.

<F5> Lets you go to a specific line number or by default back
to the beginning.

<F6> In insertion mode cuts the following line, otherwise the
line the cursor is on. Cuts all the selected lines.
The contents of the cut are always written to the
scrap board.

<F7> Turns on or off the insertion mode. When the insertion
mode is turned off, a beep is sounded.

<F8> Marks the beginning of a section to cut or copy.
You may then move down and select more lines by pressing
the <DOWN ARROW> key or up and deselect lines by pressing
the <UP ARROW> key.

<F8> Copies the selected area to the scrap board.

F9 KEY Pastes the contents of the scrap board into the definition
at the current location.

F10 KEY Terminates altering and goes directly to the START
message, bypassing the exit prompt and saving all the
changes.

CONTROL-LEFT Restores the original value of the item that you are
ARROW KEY editing.

To alter a user-defined verb you type ALTER at the START prompt. You will be asked to enter the verb's name and PRAGMA will displaying the first line of the verb. If the verb is an object verb and you wish to see the definition of the objects, simply press the <ARROW UP> key when on the first line.

When you hit <RETURN/ENTER> inside the definition of a verb and you are at the beginning of a line, you are asked if you want to save or discard the changes that you made to the verb. If you hit <RETURN/ENTER> you will go back to the START prompt and all your changes will be saved. <ESCAPE> also gets you back to the START prompt but your changes will be discarded.

If you want to EDIT a line of a verb, you hit <TAB> and the following line will be displayed in EDIT mode. You will be able to edit the first item that makes up the line. After having done this (or not), hit <RETURN/ENTER> and you will be able to edit the next item (if any) of that line. After having hit the last <RETURN/ENTER> you will have completed the editing of that line. You will then be at the beginning of the next line of the verb, where you can then go on editing the next line by hitting <TAB> again or the <UP-DOWN ARROW> keys to move around the definition.

When you are editing an item, the <ARROW LEFT> <ARROW RIGHT> <HOME> and <END> Keys will move the cursor around. The <CTRL-LEFT ARROW> key will restore the original value of the item that you are editing. Be aware that <CTRL-LEFT ARROW> is not the default value of the INPUT RESET KEY. The default value is the <ESC> key, but since the on-line help uses the <ESC> key to exit, the input reset key has to be remapped to something else.

Most of the keys are remappable in the PRAGMA description file.

LISTING AND RECAPPING

CONTROL-C Interrupts a listing. Pressing <CONTROL-C> again
KEY terminates the listing. <RETURN/ENTER> continues it.

Under DOS a <CONTROL-C> is put into the keyboard buffer
and no immediate interrupt is issued. The interrupt will
be issued in sequence. If you don't have a statement
BREAK=ON in your CONFIG.SYS, it may be hard or impossible
to interrupt a listing.

Under OS/2 the <CONTROL-C> is also put into the keyboard
buffer.

UNIX always generates an immediate interrupt regardless
of what data is in the keyboard buffer.

CONTROL-BREAK Interrupts a listing. Pressing <CONTROL-BREAK> again
KEY terminates the listing. <RETURN/ENTER> continues it.

Under DOS a <CONTROL-BREAK> will flush out the keyboard
buffer and issue an immediate interrupt, thus getting an
immediate response. If you don't have a statement
BREAK=ON in your CONFIG.SYS, it may be hard or impossible
to interrupt a listing.

Under OS/2 a <CONTROL-BREAK> does not flush out the
keyboard buffer and therefore no immediate interrupt is
issued.

UNIX may not support the <CONTROL-BREAK> key.

At the START prompt you can run interactive-only verbs that perform listings. LIST VERBS or RECAP, for example, will output a list or a verb definition on the screen.

Before starting the listing you can choose both the beginning and ending points of the listing. Simply hit <RETURN/ENTER> at both prompts if you want to see the complete listing.

The listing can be redirected to the printer, a file or the communications port if desired.

USING THE EDITOR

DEFINING A NEW VERB OR FILE

At the START prompt type VERB or FILE. PRAGMA will then define the new verb or file and you will be able to directly insert all the lines needed.

When defining an object verb, you may enter control characters into the object prompts.

DEFINING UNDEFINED VERBS

Whenever you are defining a verb you may want to use another verb that has not yet been created. PRAGMA will let you enter a name of a verb that does not yet exist and will ask you if you want to create this new verb. If you do want to create it PRAGMA will then give you the chance to add definition lines to it right away.

If you choose to do so, you simply enter all the lines you want. When you have finished you hit <RETURN/ENTER> and you can continue defining the original verb.

If you choose NOT to define the new verb at that moment, you can immediately continue adding to or editing the original verb, and the newly created verb will be an UNDEFINED verb, one without definition. It will stay an undefined verb until you go back to it with ALTER and add at least one statement line to it.

FORGETTING A VERB, FILE OR NOUN

To forget or remove a verb, file or a noun you must use the interactive-only verb FORGET. You will be prompted to type the name of the word you want to remove.

You cannot FORGET standard verbs or nouns nor can you remove a verb, noun or file that is currently being used in the definition of another verb.

OUTPUT REDIRECTION

By default the output of all the standard interactive-only verbs that produce an output of some sort is done on the screen. You may choose to redirect this output to the printer, communication port or PRAGMA.LOG file.

Simply type the device selection key immediately before typing the name of the standard word. Every time the START message is again reached, the screen is again selected.

The following keys will redirect the output:

<<F5>> redirection to SCREEN
<<F6>> redirection to PRINTER
<<F7>> redirection to COMMUNICATIONS
<<F8>> redirection to PRAGMA.LOG file.

PRINTER and COMMUNICATIONS are a file or device that have been defined in the PRAGMA description file.

When redirecting the output to the PRINTER, a line feed is inserted after every 80 characters and a form feed after every 60 lines and a final form feed at the end. This formatting occurs ONLY when printing the output of standard, interactive-only verbs from the START Message.

This formatting can be changed to suit your needs by inserting two appropriate statements in the PRAGMA description file.

The same message is always used, regardless of the output device. So if a message appears in inverse video on the screen it will go to the printer with the control characters that caused the inverse, possibly causing unwanted results when printing.

COPYING A VERB OR A FILE

After having altered a verb or a file and exiting with the <RETURN/ENTER> key, the name of the item you have been altering is requested. You may keep the original name or change it. Usually you leave the current name and to do so simply press <RETURN/ENTER>. This will get you to the START prompt and the changes that you made to the verb or file will be accepted.

If you edit the name or type a new one, and the name is accepted by PRAGMA, a new verb or file is created with the new name and the altered contents. The old definition, under the old name, remains unchanged. This simple procedure lets you create copies of verbs and files.

To be accepted a new name must not already exist as a different type. For example, if you change the name of a verb and it matches the name of an existing file, you will get an error message and get back the original name. If the name already exists for the same type of item, you will get a message that warns you that you will overwrite the already existing verb or file with the new definition of the verb or file. Lastly, if the new name does not exist, a new verb or file will be created.

REMAPPING OF KEYS

Most keys used by the editor are remappable by entering an appropriate statement in the PRAGMA description file. The OPTIONS menu, EDITOR CHOICES of the online help lists and lets you remap all the remappable keys.

DEFINITION EDITOR ON UNIX TERMINALS

Serial UNIX terminals do not support windowing, and therefore the definition editor should only be used in full screen mode when using dumb terminals.

To operate in full screen mode there must be the statement EDITOR FULL SCREEN = YES in the PRAGMA description file.

To keep the speed of a terminal acceptable you should use terminals that support scrolling up and down and insert and delete line. If the terminal has these capacities, they must be specified in the file TERMINFO.LBS. In other words, the smarter the terminal, the better the performance.

The terminal emulator program P4TERM supports windowing and the above stated restrictions do not apply.

A mathematical coprocessor will also greatly enhance the speed of the UNIX terminals, since UNIX is very slow without a math coprocessor.

See also:

Debugger
P4TERM - Introduction

Description File PRAGMA.DES

View Topic

THE DESCRIPTION FILE PRAGMA.DES

The PRAGMA.DES file is a text file that contains various parameters which are user definable.

Every PRAGMA application should have its description file. If no PRAGMA.DES description file is present when your start PRAGMA or a PRAGMA compiled application, the default values will be used. But be careful. More than likely the default values are not the ones you want and your program will then not work as it should.

The same PRAGMA.DES file (with appropriate changes for the differences inherent in the operating systems) is used for DOS, OS/2 and UNIX.

Under UNIX the name pragma.des is not capitalized.

The PRAGMA.DES file that is supplied with PRAGMA is meant to be an example. You must look at it and see if it conforms to your needs before using it.

The parameters can be listed in any sequence you like. If a parameter is not specified, PRAGMA will automatically use its default.

Unknown commands in the .DES file are ignored by the program. You may place in this file any command you want, and it will not interfere with the program. If, however, a known command is specified incorrectly, the program will abort.

The OPTIONS MENU of the online help edits the PRAGMA.DES file. This is the easiest way to make changes in it. If you use the online help to edit the PRAGMA.DES file, default values are never written to the file, and if a default value is chosen, the corresponding line will be deleted.

You can also use any text editor to directly edit the PRAGMA.DES file, taking care to use the proper syntax. Each of the parameter strings must be followed by a space, an equal sign, and another space before the value is specified. Any string therein is insensitive to case, except for the file status messages. For example:

PRINTER = LPT1

Control characters are preceded by an underline, like ^M. No quotes. But take note that when using the online help, control characters are written with a caret (^), like this ^M.

COMPILED PRAGMA APPLICATION

A compiled PRAGMA application will look for a description file with the same name as the executable file. For instance, if your program is called GREATEST.EXE it will look for a description file called GREATEST.DES. This is in order to let the various compiled PRAGMA programs that may need different description files coexist peacefully .

If no description file with the name of your program is present when your compiled program starts, the program will look for a file called PRAGMA.DES. If there is no PRAGMA.DES file, default values will be used. If you rename your compiled application, you must of course also rename your .DES file with the new name.

Description File PRAGMA.DES

View Topic

THE DESCRIPTION FILE PRAGMA.DES

The PRAGMA.DES file is a text file that contains various parameters which are user definable.

Every PRAGMA application should have its description file. If no PRAGMA.DES description file is present when your start PRAGMA or a PRAGMA compiled application, the default values will be used. But be careful. More than likely the default values are not the ones you want and your program will then not work as it should.

The same PRAGMA.DES file (with appropriate changes for the differences inherent in the operating systems) is used for DOS, OS/2 and UNIX.

Under UNIX the name pragma.des is not capitalized.

The PRAGMA.DES file that is supplied on the DOS and OS/2 PRAGMA diskettes is meant to be an example. You must look at it and see if it conforms to your needs before using it.

The parameters can be listed in any sequence you like. If a parameter is not specified, PRAGMA will automatically use its default.

Unknown commands in the .DES file are ignored by the program. You may place in this file any command you want, and it will not interfere with the program. If, however, a known command is specified incorrectly, the program will abort.

The OPTIONS MENU of the online help edits the PRAGMA.DES file. This is the easiest way to make changes in it. If you use the online help to edit the PRAGMA.DES file, default values are never written to the file, and if a default value is chosen, the corresponding line will be deleted.

You can also use any text editor to directly edit the PRAGMA.DES file, taking care to use the proper syntax. Each of the parameter strings must be followed by a space, an equal sign, and another space before the value is specified. Any string therein is insensitive to case, except for the file status messages. For example:

PRINTER = LPT1

Control characters are preceded by an underline, like ^M. No quotes. But take note that when using the online help, control characters are written with a caret (^), like this ^M.

COMPILED PRAGMA APPLICATION

A compiled PRAGMA application will look for a description file with the same name as the executable file. For instance, if your program is called GREATEST.EXE it will look for a description file called GREATEST.DES. This is in order to let the various compiled PRAGMA programs that may need different description files coexist peacefully .

If no description file with the name of your program is present when your compiled program starts, the program will look for a file called PRAGMA.DES. If there is no PRAGMA.DES file, default values will be used. If you rename your compiled application, you must of course also rename your .DES file with the new name.

CONVERTING FROM PRAGMA 3 TO PRAGMA 4

Description file parameters are the counterparts of the parameters found in the Setup System Parameters menu of PRAGMA 3.

When converting a PRAGMA 3 application, the PRA2PFM program will create a PRAGMA.DES file with the correct parameters. These values are copied out of PRVOCAB during the conversion. When there are more than one set of values for a given parameter, the ones from the first user are used.

The file manager error messages are read from your PRSYSTEM.XXX file and become part of the description file and therefore work like they do in your original PRAGMA program, even if you have translated them into another language.

Some parameters are NOT automatically generated when performing a conversion from PRAGMA 3. If needed they have to be manually inserted to conform to your equipment and operating system. (PRINTER, COMMUNICATIONS, etc.)

Displaying Text

View Topic

Drawing Lines and Boxes

View Topic

EDITOR HELP 6000 - 6999

View Topic

Environment Configuration - DOS

View Topic

ENVIRONMENT CONFIGURATION - DOS

We recommend that you use DOS 5.0 or above.

DOS 5.0 maximizes the amount of free memory available to PRAGMA. This is only important if you are using the system call function from within PRAGMA, since whatever program you will be calling with system call will be also limited by the amount of free memory available.

Earlier versions of DOS will work, but may require different configuration settings. But they must be DOS versions 3.3 or higher.

We recommend that you use at least 3 MB of extended memory to avoid slowing down your system due to excessive memory swapping to disk. Thus the total amount of memory present should be at least 4 MB, and it all should be accessed by a 32 bit wide path.

With the DOS version the only way to run out of memory space for your PRAGMA program is if you completely fill the memory of your computer and also completely fill your hard disk with the virtual memory file.

If, when loading the PRAGMA DOS version you get an extender error message and your machine locks up, the PRAGMA extender is fighting with some other extender over memory. Temporarily eliminate everything from your CONFIG.SYS and AUTOEXEC.BAT which is not strictly necessary until you isolate the culprit.

A typical CONFIG.SYS in DOS 5.0, that does not make use of the high memory, might look like this:

BUFFERS=30,2
FILES=50
BREAK=ON
INSTALL=C:\DOS\SHARE.EXE
DEVICE=C:\DOS\ANSI.SYS
INSTALL=C:\DOS\FASTOPEN.EXE
SET TERM=DOSMEM or DOSMEMMONO

This assumes that DOS resides in a directory named C:\DOS.

If you try to run the new batch file and you run out of environment space, also add:

SHELL=C:\COMMAND.COM/P/E:1024

to your CONFIG.SYS. This assumes that COMMAND.COM is in your root directory and you give your environment a size of 1024 bytes, which should be plenty.

BUFFERS
The first parameter sets the number of disk buffers and the second parameter sets the maximum number of sectors that can be read or written in one I/O operation. You should open as many disk buffers as possible for PRAGMA. The maximum number of sectors should be set to two.

FILES
Sets the number of open files that the MS-DOS system calls can access. Open at least 50. If you don't open enough files you may suddenly get a "file not found error" the moment you try to open more files than the set number. Don't forget that all the system files (PRAGMA.EXE, PRMSG.PFM, etc.) also count, and if you use Btrieve in safe mode you are actually always opening two files for every file write access done by PRAGMA.

BREAK
If BREAK is ON, MS-DOS extends <CONTROL-C> checking to functions such as disk reads and writes.

SHARE.EXE
You must always install SHARE, because all PFM files are opened using its file locking to control multiuser access. SHARE is also required to run FILEUTIL and PRA2PFM. If your application does a lot of record locking, you may have to add the optional L parameter that allows a greater number of locks than the default number of 20.

ANSI.SYS
This is the device driver that lets you use ANSI escape sequences to allow you to change graphics functions and affect the movement of the cursor. You must have ANSI.SYS loaded if you choose to write to the screen by going through DOS and you use a DOSANSI or DOSANSIMONO terminal type.

FASTOPEN
This should also be in your CONFIG.SYS file. Although not strictly necessary, it will improve file access speed.

SET TERM
This tells your programs what information to extract from the TERMINFO.LBS file. Placing SET TERM=DOSMEM in your CONFIG.SYS will work, but will give an error message on the screen. If you want to avoid this you can put SET TERM into your AUTOEXEC.BAT file. If you are using a monochrome screen you should use the DOSMEMMONO option to suppress color commands.

CACHE
We recommend that you also install a cache program. It really does not matter what cache you use, as long as it buffers data for writing and is write-back (not write-through).

LOADING DOS 5.0 HIGH

In DOS 5.0, DOS itself, as well as other programs like network shells, etc., may be loaded into high memory. In the best case, you can have about 620K of free memory.

The DOS version of PRAGMA uses a DOS extender that does not use any low memory. If you load DOS and everything high, you are actually taking memory away from PRAGMA. Also an EMM manager will slow down certain operations of the DOS extender.

If, when loading the DOS version of PRAGMA your machine locks up, the DOS extender of PRAGMA is in conflict with some other extender or the extended memory manager over memory. To isolate the culprit temporarily eliminate everything that is not strictly necessary form your CONFIG.SYS and AUTOEXEC.BAT file.

The ability of DOS 5.0 to load DOS high and provide more low memory is only good if you need to do a system call of a normal low memory DOS program.

When using DOS 5.0, it by default loads DOS high during installation by using the DOS=HIGH command in CONFIG.SYS. You need HIMEM.SYS loaded. You also probably want the UMB parameter on the DOS=HIGH command. Further, the EMM386 program can provide upper memory blocks to DOS which can be used to load network shells, etc. Lastly, DEVICEHIGH statements can be then used to load device drivers into these high memory blocks. A typical CONFIG.SYS for loading high DOS 5.0 follows :

DEVICE=C:\DOS\HIMEM.SYS
DOS=HIGH,UMB
DEVICE=C:\DOS\EMM386.EXE NOEMS
DEVICEHIGH=C:\DOS\ANSI.SYS

In your AUTOEXEC.BAT, you may then use LOADHIGH commands to load TSRs into high memory blocks. Following is a typical AUTOEXEC.BAT for DOS 5.0 :

LOADHIGH C:\DOS\DOSKEY
LOADHIGH C:\DOS\SHARE

Using this approach, you can usually get everything loaded high, and have as much low memory as possible free for PRAGMA. This is the goal. Sometimes you will have to juggle the order in which you attempt to load things, as the high memory is used on a first come, first served basis. If a small program comes along first, that uses a big memory block, much space is wasted. Generally, try to load the biggest things first. This is not an absolute rule, but it seems to have worked for us. On some machines, you may find that there just is not enough high memory to load everything, or maybe the biggest things won't load.

There are many options available to you when using the LOADHIGH commands. The above is only a suggestion. Refer to the DOS manual for complete information about these commands.

RUNNING PRAGMA UNDER WINDOWS

To run PRAGMA under Windows put the file WEMU387.386 into the directory \WINDOWS\SYSTEM and to your SYSTEM.INI in, the [386Enh] section, add the following line:

device=\WINDOWS\SYSTEM\WEMU387.386

The file WEMU387.386 is found on the PRAGMA release diskette.

See also:

Operating Systems Overview
Installing PRAGMA on DOS
Terminfo

Environment Configuration - OS/2

View Topic

Environment Configuration - UNIX

View Topic

Error Handling

View Topic

ERROR HANDLING

When running a PRAGMA program and a problem occurs, PRAGMA aborts and opens the debugger, to help track the problem.

Typically these problems are invalid numeric values or file errors when using the PRAGMA 3 emulation.

The debugger can also be accessed when a program is running by pressing <CONTROL-C> twice. Depending on the operating system and what the PRAGMA program is doing at that particular moment, you may have to press also <RETURN/ENTER> after the <CONTROL-C>'s to stop the execution of the program.

The PRAGMA debugger splits the screen into two parts or windows.

The upper window (the definition view window) will show the part of the verb that was running when the error or interrupt occurred, with the cursor on the current line.

The lower window (the command window) will show the verb name, the line in which the interrupt occurred and the situation that caused the execution to pause. The DEBUG prompt.will also be displayed.

The cursor will be in the lower window. To move it to the upper window hit the <F4> key.

In the upper window you can look at the verb definition by moving around in the usual way. You are not allowed to do any editing to the verb, nor are you moving the execution pointer when moving around.

In the lower window you may perform any operation that can be done at the DEBUG prompt. Hitting the <RETURN/ENTER> key will automatically resume the execution of the program where it left off. The <F1> key will summon the online help.

If the interrupt occurred due to an error like invalid numeric value, etc. you cannot continue with the execution of the program. You must either fix the problem or abort. If the error was caused by a file error in mock internal emulation (and ONLY there) you can continue without fixing the problem. The program will continue at the next instruction. But be aware that the results may not be what they should.

To abort type ABORT EXECUTION (or its abbreviation AEX) at the DEBUG prompt.

Whenever the program is interrupted by either the user or an error, PRAGMA will automatically make an entry into the PRAGMA.LOG file.

Before aborting it might be useful to run the verb SHOW VERB STACK (SVS). To redirect the output of SHOW VERB STACK to the PRAGMA.LOG file for future reference hit the <F8> key before entering the verb name.

See also:

Debugger
Error Messages
Log File PRAGMA.LOG

Error Messages

View Topic

ERROR MESSAGES AND TROUBLESHOOTING

Should you have a problem running PRAGMA, more often than not it will be due to the way it interacts with the operating system. The following pages will help you in determining the causes.

If you are using the DOS extender version, you may get error messages from the extender. These messages usually say OS/386 or OS/286. In some cases they may say GP (general protection violation) something. In most cases the extender finds itself in conflict with another program that uses extended memory or there is not enough extended memory available. Sometimes other programs that use extended memory may cause the extender to lock up or take away all the available extended memory. In these cases, eliminate all programs that might use extended memory (caches are prime targets). In order to find out which one causes the problem, add them back one by one until you find the culprit.

Always reboot your machine after an extender crash, because DOS might be left behind in an unstable state.

Communications port error, ABORTING.

An error has occurred during SEND/RECEIVE, or when opening the
communications port.

Error accessing PRAGMA.DES, ABORTING.

An error has occurred when reading PRAGMA.DES at startup.

Error during file operation, filename ?, status is ?, ABORTING.

An error occurred during a file operation, and the file is using
mock internal emulation.
If, under DOS, the error says NO SUCH FILE, did you, in the
CONFIG.SYS, set a high enough number of open files that DOS can
access?

File manager bitmap error, ABORTING.

PFM has detected a corrupted file. You do have a backup, don't
you?

File manager chain error, ABORTING.

PFM has detected a corrupted file.

File manager disk read error, ABORTING.

An error has occurred when reading a PFM file.

File manager disk write error, ABORTING.

An error has occurred when writing to a PFM file.

File manager index error, ABORTING.

PFM has detected a corrupted file.

File manager record error, ABORTING.

PFM has detected a corrupted file.

Help Text in the Online help cannot be accessed.

Set the parameter RECORD SIZE in PRAGMA.DES to 16384.

Invalid Numeric Value, ABORTING.

PRAGMA has encountered an invalid numeric value in a noun,
usually from a math routine, but it can also happen if the key
number noun of a file is bad.

If you get this message at the beginning of a program, the first
time it comes across a number with decimals, check that the
DECIMAL convention in the PRAGMA.DES file is set correctly.

Invalid parameter in PRAGMA.DES, ABORTING.

Something invalid has been found in PRAGMA.DES at startup.

Memory error, ABORTING.

The PRAGMA memory manager has detected inconsistent data in
memory. It should never happen in normal usage, but could be due
to a program bug.

Message error, ABORTING.

PRAGMA has detected an error in PRMSG.PFM, or the file is
missing.

No more memory available for allocation, ABORTING.

PRAGMA has run out of free memory. This should usually only
happen when using the 8088 version of PRAGMA. (Did you put the
WRITE NOUNS = YES statement into PRAGMA.DES if you are using the
DOS88 version?)
It may happen with other versions (that have virtual memory) in
extreme cases if the disk space in the swap area is full.
It may also happen because of bugs or uninitialized nouns in the
compiled version.
PRAGMA has tried to access a corrupted PFM or Btrfieve file.

PRAGMA aborts with an error message, before starting. - OS/2

You forgot to add the statement IOPL=YES to the CONFIG.SYS file.

PRAGMA crashes trying to save a record, for no explainable reason.

Check the free available disk space. Remember that the extender
also needs some free disk space. This is a difficult problem to
troubleshoot because after the crash the extender deletes the
large file from the hard disk before closing down, leaving you
wondering what happened and with the file you tried to write to
corrupted.

Printer error, ABORTING.

An error occurred during printing, or when opening the printer
port/file.

Printer is not printing, but program continues as if it had printed

The PRAGMA.DES file does not contain a PRINTER statement, so all
the data sent to the printer is thrown away.

Screen Initialization error, ABORTING.

This is usually caused by a missing TERMINFO.LBS, or no TERM=???
in the environment.

Did you remember to put a SET TERM = DOSMEM in your AUTOEXEC.BAT
file if you are under DOS? Under OS/2, did you include
SET TERM = OS2ANSI in the CONFIG.SYS file? Is the file
TERMINFO.LBS in the same directory as your program or did you put
it into a subdirectory called \USR\LIB\TERMINFO?

If you get this error under UNIX something went wrong with your
installation or you accidentally erased the TERMINFO.LBS file. In
either case, you should reinstall PRAGMA for UNIX.

It may also occur when no more free memory is available (in the
DOS 8088 version).

Security error, ABORTING.

PRAGMA cannot read the security block, or it is invalid.

You forgot to plug a PRAGMA security device into a parallel port.
You are using the wrong security device.
You attached a printer to the security device and did not turn it
on.
Your machine is too fast. Change the block timing delay in the
parameter file PRAGMA.DES.
Your security device is broken. It can happen.

Standard error, ABORTING

PRAGMA has detected an error in PRSTD.PFM, or the file is
missing.

System hangs after the Logical copyright message, but before
displaying the START message - DOS

Did you remember to put an INSTALL=C:\DOS\SHARE.EXE statement in
your CONFIG.SYS file?

System hangs after the Logical copyright message, but before
displaying the START message - UNIX

Did you give read and write permission to the .PFM files?

System hangs before the Logical copyright message. - UNIX

Is the pragma.des file correct? (Under UNIX the name pragma.des
is not capitalized.) Try taking out the pragma.des file. Are
you trying by mistake to access a DOS executable file?

Terminated by operator, ABORTING. - COMPILED VERSIONS

The program has been terminated by CTRL-BREAK (DEL in UNIX).

Vocabulary error, ABORTING.

PRAGMA has detected an error in PRVOCAB.PFM, or this file is
missing.

Extender Configurations

View Topic

File Manager - Btrieve Mode

View Topic

FILE MANAGER - BTRIEVE FILE MODE

The Btrieve file mode can be used with either PFM or Btrieve as filemanager, but in this mode you cannot access the PRAGMA Fileserver.

The main reason for using this operating mode is to have Btrieve as filemanager or because you want to use segments in your indexes. Although the following pages give a brief explanation on how to use segments, it would transcend the scope of this manual to offer an in-depth explanation of segments. A good place to learn more about segments is the Btrieve manual.

Btrieve imposes the limitation that all the references are expressions and of the same length. This obliges you in your program to "pad" all your references with spaces to the selected length and to convert all numeric references to expressions and pad them with leading spaces or zeros. This is not strictly true for PFM files used in Btrieve mode, but we suggest that if you use Btrieve mode, use it in such a way that you can switch from PFM to Btrieve without having to make program changes.

Whether you are using PFM or Btrieve as file manager you must always create an empty file on the operating system level by first writing a text description file with a text editor and then using FILEUTIL to create an empty PFM file, or BUTIL to create an empty Btrive file.

A record operating in Btrieve mode with PRAGMA has a fixed length part, which must contain all the indexes. (Btrieve calls them KEYS). The maximum length of this part is 255 bytes. Also included in this part must be a 3 byte header for each field. A key is not necessarily the same as a field; a key has a start point and an end point within the fixed length portion of the file record.

EXAMPLE OF A BTRIEVE MODE PFM FILE

We will use an address file with three indexes:

sequential number
name
city

Number 123

Name Smith Joe
Address Hard Disk Drive 77
City Santa Clara
State CA

Then we must decide the maximum length of each reference. This length will be the maximum number of characters that we can enter into the noun, but is NOT necessarily what PRAGMA will use to compare the references. PRAGMA will use the segments (if any) to compare the references.

Each record will have a unique number (no duplicates) and we foresee a maximum of 99,999 records. Since Btrieve does not allow numeric references, this number converted to an expression will be a maximum of 5 characters long.

The name of the person will be unique in this example, that is, we cannot have two Joe Smiths in our address database. The maximum length that a name can be is 30 characters.

The city will have to allow for duplicates, since we expect to know quite a few people living in the same town. Again, a maximum length of 30 characters is chosen.

Then define the file in PRAGMA by typing the word FILE (or the abbreviation FL) at START in the definition editor and you will be prompted and asked to enter the following information:

FILE called AD2 ADDRESSES

The short name is AD2^ADDR
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 0
The number of indexes is 1
The significant length of index 1 is

1 AD INDEX NOUN
2 AD NUMBER
3 AD NAME
4 AD CITY
5 COMMENT you may add more nouns if you want.
6 AD STREET ADDRESS

LONGNAME

(AD2 ADDRESS) The name of the file in the PRAGMA program. It can be up to 31 characters long and may contain alphanumeric characters, nonalphanumeric characters and spaces. You may NOT use an underline.

SHORTNAME

(AD2^ADDR) The name that PRAGMA uses to find a PFM (or Btrieve) file in the operating system. When you create a new file in PRAGMA named LONGNAME, SHORTNAME is automatically generated for you, respecting the shortname naming convention. Shortname allows only alphanumeric characters and the underline character in the name and cannot be more than 8 characters long.

If you don't like the shortname you may edit it any time you like. But remember that the shortname and the name of the file on the operating system must always match, otherwise you get a "FILE NOT FOUND" error. If you already have a file on the operating system, immediately change its name also.

BTRIEVE OPEN MODE

Applies only if you will be using Btrieve files. It lets you choose if you want to open the Btrieve file in SAFE or FAST mode. The SAFE mode is the default, and is indicated by a 0 (zero). The FAST mode is obtained by inserting a -1. But be careful, depending on the operating system and available memory there is a maximum number of FAST Btrieve files that can be opened at the same time. Under DOS the maximum number is between 15 and 20.

PFM UNIT SIZE

Does not apply for this mode.

MOCK FLAG

Tells the filemanager in what mode to operate. The Btrieve mode is 0 (zero).

NUMBER OF
INDEXES

Does not apply for this mode.

SIGNIFICANT LENGTHOF INDEX

Does not apply for this mode.

After having completed the header of the file definition you must enter the nouns that are part of the file definition. In the following explanation we continue with our example.

AD INDEX NOUN

Immediately following the file header you MUST enter the index selection noun. This noun will tell the PFM or Btrieve filemanager which index to use when looking for a record. The index selection noun must contain a number.

Computers don't always have to be logical. So, to retrieve a record with index number 1, copy a zero to the index selection noun, to retrieve a record with the index number 2, you copy a 1 to the index selection noun, and so on.

Before you perform ANY file access in your program, ask yourself whether the index selection noun is set correctly. Better reinitialize it once again. An index noun with the wrong value can be a very difficult bug to trace in your application.

REFERENCE NOUNS

The file definition MUST contain the reference nouns after the index
selection noun. They MUST be of fixed length. Duplicate references are allowed ONLY if we take care of them with segments when we define the empty file.

In our example, we want every record to have its own number, so AD NUMBER will not pose a problem. But you MUST convert the number to an expression and pad it to a fixed length. In our example we have to pad it to a length of 5 with leading zeros. The number 865, for example, would become the expression "00865".

AD NAME will always be unique, while AD CITY will allow for duplicates. A maximum of 30 characters has been chosen for both nouns, so both will have to be padded to this length with spaces.

OTHER NOUNS

After the reference nouns you may of course add any noun you wish to complete your file record.

CREATING A BTRIEVE MODE PFM FILE

An in-depth explanation of the description files, both for PFM and Btrieve, can be found in the FILE MANAGER - DESCRIPTION FILE section. FILEUTIL and BUTIL are explained in the FILE MANAGER - FILEUTIL and FILE MANAGER - BUTIL sections.

Go to the operating system and with your favorite text editor create a text file called AD^ADDRE.DES that looks like this:

page=256 (calculated minimum page size, then rounded up to the
nearest power of two)
key=3 (we have 3 key nouns altogether)
position=4 (first key starting position, just past the first field)
length=5 (length of the first key)
segment=n (no segments follow for this key, no duplicates allowed)
position=12 (second key starting position, given by 4+5+3=12 )
length=30 (length of the second key)
segment=n (no segments follow for this key, no duplicates allowed)
position=45 (third key starting position, given by 12+30+3=45 )
length=30 (length of the second key)
segment=y (a segments follows for this key)
position=4 (segment is first key)
length=5 (length of the first key)
segment=n (no other segments follow)

Try to fit an entire file record onto one page. But do not make the page size enormous, or every file record will waste a lot of space. A good suggestion is to first calculate the size of a file record. Make the page size at least that big. This is considered to be a minimum realistic size. Of course, this must be at least as big as the bare minimum size, as calculated by the formula shown on the following pages. Lastly, you may wish to round the page size to the nearest multiple of two, if it is close, or at least round it up to a number that is the sum of some powers of two (like 384 + 256). The closer you get to a power of two, the faster disk I/O is. Especially good are multiples of 512. But that is wasteful of disk space if the records are small.

Do NOT include what is in the parenthesis. That is only meant as an explanation for this example. In the real file you are not allowed to write any comments. Also you must write only one statement on each line. No tabs, no blank lines are allowed.

To make the third key noun unique we add to it the first key noun as a segment, thereby creating a unique combination. Another way to visualize a segment is as if you were to JOIN inside PRAGMA the third key noun to the first key noun and thus insure a unique name.

Then, from the operating system prompt, run FILEUTIL:

FILEUTIL -CREATE AD^ADDRE.PFM AD^ADDRE.DES

You will end up with the empty AD^ADDRE.PFM file. If you get an error, you probably made a typing error in the description file or you calculated too small a page.

USING A BTRIEVE MODE PFM FILE

To enter new data into the file you do something like this:

10 COPY the value 0 to the noun ADDRESS KEY
11 COMMENT Just to make sure that this noun is initialized
...
20 COPY the value "00078" to the noun ADDRESS NUMBER
21 COMMENT The expression ADDRESS NUMBER must always be 5
characters long.
22 COMMENT Key nouns must always be expressions, even if they
contain numbers.
23 COPY the value "John Smith " to the noun
ADDRESS NAME
24 COMMENT The expression ADDRESS NAME must always be 30
characters long.
25 COPY the value "New York " to the noun
ADDRESS CITY
26 COMMENT The expression ADDRESS CITY must always be 30
characters long.
...
30 SAVE reference 0 in file AD ADDRESS
31 COMMENT Reference, when SAVING, is not important and is ignored
by PRAGMA.
32 IF the value FILE STATUSO "^" the value 0
...

It is essential that the key nouns be expressions and that they always be the same length, as specified in the description file. To satisfy this requirement you can write small verbs that automatically pad your nouns to the desired length with spaces or zeroes.

Whenever you access a PFM file you must check the FILE STATUS to make sure that the operation was completed successfully. After all, somebody could have accidentally erased all your files!

To list all the addresses sorted by ADDRESS NAME you do something like this:

10 COPY the value 1 to the noun ADDRESS KEY
11 BEGIN FIRST in file AD ADDRESS
12 LABEL this line with
LOOP
13 GET NEXT in file AD ADDRESS
14 IF the value EXTERNAL ECHO "=" the value "OK"
do
DISPLAY the value ADDRESS NAME
DISPLAY the value LINE FEED
else
RETURN
end
...
20 GO TO line labeled LOOP

If, instead, you want to list the addresses sorted by ADDRESS CITY, you simply COPY a 2 to the noun ADDRESS KEY in line 10.

A quick way to list your key nouns is by running the standard verb LIST REFERENCE from the start message. LIST REFERENCE will display the key noun and its segment, if it has one.

USING A BTRIEVE MODE BTRIEVE FILE

The above example also applies for Btrieve. The only difference is that the description file is slightly different (as explained in the FILE MANAGER - BUTIL section) and that you must use BUTIL instead of FILEUTIL.

To switch from PFM to Btrieve or vice versa don't forget to edit the filemanager parameters in PRAGMA.DES.

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Native Mode
File Manager - Fileutil
File Manager - Butil
File Manager - Description File

File Manager - Butil

View Topic

FILE MANAGER - BUTIL

BUTIL is the utility that creates an empty Btrieve file with the characteristics you provided in the description file.

BUTIL is supplied on the Btrieve diskette from Novell.

To run BUTIL you must have already loaded Btrieve.

For a more in-depth discussion of Btrieve please refer to the Btrieve reference manual.

THE BTRIEVE DESCRIPTION FILE

Before you can use a Btrieve file in PRAGMA you must create an empty BTR file with the characteristics you want using the utility BUTIL. But before BUTIL can set up a new file, you have to provide it with a description file that contains some specific instructions.

On a text editor write a description file as follows:

record=[number]
variable=y
key=[number between 1 and 24]
page=[number, multiple of 512, up to 4096]
position=[number]
length=[number]
duplicates=[y or n]
modifiable=[y or n]
type=string
alternate=n
null=n
segment=[y or n]

These parameters have the following meaning:

record=

Defines the logical data record length for the file. The minimum length must be large enough to contain all the keys defined for the file plus three bytes per key noun and it cannot be less than four bytes. When using variable length records, the record length specified here should correspond to the fixed length portion of the record.

variable=y

Y equals yes, variable size records.

key=nn

Specifies the number of keys that are to be used, with a minimum of one and no more than 24.

page=nnn

Defines the physical page size for the file and must be a multiple of 512, from 512 up to 4096, inclusive. The default page size is 1024. To create with BUTIL a file with a page size greater than 1024 you must load BTRIEVE with the /P parameter.

position=nnn

Indicates the position in the record where the first key begins. The first key always starts after a three byte header.

length=nnn
Defines the length of the key or key segment field.

duplicates=y/n

Specify Y if you want to allow duplicates for the key.

modifiable=y/n

Specify Y if you want the values for this key to be modifiable.

type=string

All keys are type string.

alternate=y/n

Select Y if you want Btrieve to sort this index by an alternate collating sequence other than the standard ASCII sequence. Normally you would choose N.

null=n

No null keys allowed.

segment=y/n

Specify Y if the key you are defining has another segment.

CREATING A BTRIEVE FILE

After having created the description file on a text editor save it where you have the Btrieve utility BUTIL and run CREATE to generate an empty Btrieve file. To run CREATE enter a command following this format:

BUTIL -CREATE FILENAME.BTR FILENAME.DES

FILENAME is the name of the empty Btrieve file you want to generate and must have the extension .BTR.

FILENAME must be no longer than eight characters and must be the same name as the SHORTNAME in the header of the file definition inside PRAGMA.

FILENAME.DES is the name of the file you just created on the text editor that contains all the specifications.

SINGLE KEY BTRIEVE FILE

The following is an example of a description file for a Btrieve file that can be accessed by one key and the key is six bytes long. No duplicates are allowed in the key.

record=9 (logical data record length)
variable=y
key=1 (only 1 key)
page=512
position=4 (key starting position)
length=6 (key length)
duplicates=n (no duplicates in the key)
modifiable=n (key values not modifiable)
type=string
alternate=n
null=n
segment=n (no segments, therefore each key must be unique)

The first (and only) key noun starts at position four, to allow for the three byte long header.

MULTIPLE KEY BTRIEVE FILE WITHOUT DUPLICATES

This type of file can be accessed by more than one key (in our example below, by two keys) but does not allow for duplicates in the key nouns. That is, every key noun in every record must be different from every other record. The first key noun is six bytes long, the second 10 bytes long.

Btrieve looks at the whole key, all segments combined. It does not matter if any of the individual segments in a key are duplicated or not, as long as the whole key is not duplicated. Remember that segment, key and key nouns are three different things.

record=22 (fixed length portion of record)
variable=y
key=2 (2 keys)
page=1024

position=4 (1st key starting position)
length=6 (1st key length)
duplicates=n (no duplicates in the key)
modifiable=n (key values not modifiable)
type=string
alternate=n
null=n
segment=n

position=13 (2nd key starting position)
length=10 (2nd key length)
duplicates=n (no duplicates in the key)
modifiable=n (key values not modifiable)
type=string
alternate=n
null=n
segment=n

For each additional key noun you must repeat the section of the description file that goes from "position" to "segment".

The first key noun stops with position nine. The second key noun starts at position 13. Position 10,11,12 allow for the three byte long header of the second key noun.

MULTIPLE KEY BTRIEVE FILE WITH DUPLICATES

This type of file can be accessed by more than one key (in our example below, by two keys) and does allow for duplicates in the second key noun. The first key noun is six bytes long, the second 20 bytes long.

To be able to have duplicates in keys you combine the key that may have duplicates with another key, thereby creating for Btrieve an artificial key that does not have duplicates.

record=32 (fixed length portion of record)
variable=y
key=2 (2 keys)
page=1024

position=4 (1st key starting position)
length=6 (1st key length)
duplicates=n (no duplicates in the key)
modifiable=n (key values not modifiable)
type=string
alternate=n
null=n
segment=n

position=13 (2nd key starting position)
length=20 (2nd key length)
duplicates=y (duplicates in the key)
modifiable=y (key values modifiable)
type=string
alternate=n
null=n
segment=y
position=4 (1st key starting position)
length=6 (1st key length)
duplicates=n (no duplicates in the key)
modifiable=y (key values modifiable)
type=string
alternate=n
null=n
segment=n

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Native Mode
File Manager - Fileutil
File Manager - Description File

File Manager - Description File

View Topic

FILE MANAGER - THE PFM DESCRIPTION FILE

If you are not using the PRAGMA native mode, you must create an empty PFM file with the characteristics you want using the utility FILEUTIL.

But before FILEUTIL can set up a new file, you have to provide it with a description file that contains some specific instructions.

On a text editor write a description file as follows:

page=[number]
key=[number]
position=[number]
length=[number]
segment=[y or n]

These parameters have the following meaning:

page=nnnn

The PFM unit size. The folowing explanation is quite complex. If you don't want to be concerned with all this, 128, 256, 512 or 1024 are always good choices for speed, albeit they may waste some disk space. FILEUTIL will not let you use too small a unit size anyway.

PFM allocates disk space from the operating system in what are called units. These units are variable size, and the size is set when the file is created. The length of a PFM file, as seen in the directory, is always a multiple of the unit size.

At the operating system level, the operating system usually allocates disk space on a disk sector basis, or a multiple of disk sectors. In DOS this is called a cluster, and it is usually anywhere from 2K to 16K in size. You need not be concerned with this, except that the operating system will map between the different sizes of its allocation units (or clusters in DOS) and the PFM unit, and this will have an influence on speed. If you make the PFM unit size the same as the disk sector size (usually 512 K) this will make the job for the operating system easier and thus faster.

PFM files have two different types of units for storing data: the data unit and the index unit. When the unit size is less than 1024 the index units will be 4 times as large as the specified unit size, to help pack the indexes and speed lookups. For unit sizes greater than 1024 the data units and the index units will be of the same size.

There is an absolute minimum PFM unit size of 92. The maximum size is 8K. This size does not have to be a power of two, like in Btrieve, but can be any number at all. It will be rounded up to the nearest multiple of four. Use care when choosing the size for each file. There are four factors to consider when making this decision.

First, a unit size which is a power of two, or a multiple of the disk sector size (which is also a power of two), will generally be faster, because the operating system will not have to split units between disk sectors. However, simply rounding the unit size up to the next highest power of two rather than the minimum unit size necessary for the given situation will generally waste disk space. This decision is up to you. Speed versus space.

Next, the unit size chosen must be big enough to contain at least two of the largest index entries of the file. The PFM software assumes that only one unit is needed to store the control unit. The size of this control unit is variable. The absolute minimum size is 92. The minimum size in a particular case can be found by taking the longest significant length of all the indexes of the file, add one to it and then round it up to a multiple of four, if necessary. Then add four to this to account for the index pointer. Then double that, to be the size of two such entries. Then add 16 to that, for the index sector overhead. The unit size must never be less than this number.

There is also a second consideration, and formula, to calculate minimum unit size. When a file has more than one index, the absolute minimum unit size becomes bigger also. This is because all of the information about the indexes must be small enough to fit in one unit. For each index beyond the first, add 36 to the minimum unit size of 92. The minimum size of 92 includes space for one index; each additional index requires 36 extra bytes of space. The above size of 36 bytes per index presumes single segment indexes. For each additional segment, add eight.

The absolute minimum unit sixe for a file must be the largest of the two considerations listed above or at least 92.

Third, the index units, if bigger, can obviously hold more index pointers per unit. This can cause the index to be more compact and can perhaps make searching faster. However, bigger index units may also be wasting space if not completely filled.

Last, the file record data itself will be stored in units as well. If the file record data is too big to fit in one unit, a chain of units will be created of the length required. If, however the unit is made big enough to hold all of the file record data for a single record, it can be read all in one disk operation, which should be faster than making multiple disk operations to read a chain. But if the records vary greatly in size in the same file, using a unit size big enough to hold the biggest record will waste a lot of space for the small records. Generally, the best situation is to have a file with more or less constant record size, and choose the unit size accordingly. There are twelve bytes of the unit used for control information in a data unit, so be sure to account for this in your calculation.

key=nn

The number of keys to this file. There is no limit to the number of keys. Each key can be composed of multiple segments, again, with no limits.

position=nnn

The starting position within the record of a key segment. Positions start from one at the first byte of a record. There is also a three byte header per field, which should be skipped over.

length=nnn

The length of this key segment in bytes.

segment=y/n

Whether or not there is another segment for this key.

These options can be specified in either upper or lower case, or any mixture. They must be specified each one to a line, with no blank space before, after, or in-between them. Also, they need to be specified in a certain order. The page option must be first, followed by the key option. Then the position, length, and segment options may occur, repeated as many times as necessary.

For compatibility with Btrieve and Butil, Fileutil can read a description file that first lists key and then page, just like the description file for Btrieve.

SINGLE KEY PFM FILE

The following is an example of a description file for a PFM file that can be accessed by one key and the key is six bytes long. No duplicates are allowed in the key.

page=128 (file unit size)
key=1 (only one key)
position=4 (key starting position, just past the first field
header)
length=6 (key length)
segment=n (no segments follow, therefore key must be unique)

Please note that the PFM description file can only have one item per line. You are not allowed to have multiple items per line.

The first (and only) key noun starts at position four, to allow for the three byte long header.

MULTIPLE KEY PFM FILE WITHOUT DUPLICATES

This type of file can be accessed by more than one key (in our example below, by two keys) but does not allow for duplicates in the key nouns. That is, every key noun in every record must be different from every other record. The first key noun is six bytes long, the second 10 bytes long.

page=256 (file unit size)
key=2 (two keys)
position=4 (key starting position, just past the first field
header)
length=6 (key length)
segment=n (no segments follow, therefore key must be unique)
position=13 (second key starting position, 4 + 6 + 3 = 13)
length=10 (key length)
segment=n (no segments follow, therefore key must be unique)

For each additional key noun you must repeat the section of the description file that goes from "position" to "segment".

The first key noun stops with position nine. The second key noun starts at position 13. Position 10,11,12 allow for the three byte long header of the second key noun.

MULTIPLE KEY PFM FILE WITH DUPLICATES

This type of file can be accessed by more than one key (in our example below, by two keys) and does allow for duplicates in the second key noun. The first key noun is six bytes long, the second 20 bytes long.

PFM does not support duplicate keys.

To be able to have duplicates in keys you combine the key that may have duplicates with another key or a segment of a key, thereby creating for PFM an artificial key that does not have duplicates.

page=1024 (file unit size)
key=2 (2 keys)
position=4 (1st key starting position)
length=6 (1st key length)
segment=n (no segments follow, therefore key must be unique)
position=13 (2nd key starting position)
length=20 (2nd key length)
segment=y (yes a segment follows)
position=4 (1st key starting position)
length=6 (1st key length)
segment=n (no segments follow)

THE PFM VOCAB DESCRIPTION FILE

If you want, you can create an empty PRVOCAB.PFM file with FILEUTIL but you must add the line nouns=n to the standard description file. This will tell the file manager that this file consists of raw binary data (PRVOCAB.PFM file). It is really only useful if you wish to create a PRVOCAB with a different unit size than the default of 256.

The default description file for PRVOCAB.PFM looks like this:

nouns=n
page=256
key=2
position=5
length=32
segment=n
position=1
length=1
segment=y
position=5
length=32
segment=n

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Native Mode
File Manager - Fileutil

File Manager - Mode 1 Operation

View Topic

PRAGMA 3 INTERNAL EMULATION MODE (MODE 1)

The PRAGMA 3 internal emulation mode can use either PFM or PRAGMA Fileserver as filemanager. With the single limitation of not fully supporting numeric references, you can also use Btrieve.

This operating mode is automatically chosen when converting a PRAGMA 3 application for the PRAGMA 3 internal files. As the name implies, this operating mode closely emulates the way PRAGMA 3 handles internal files. That means that all the restrictions found in PRAGMA 3 and in the internal files will apply, excepting the file size, which is not limited in this mode.

We do not suggest that you use this mode when writing a new application with PRAGMA 4. Nor should you use this mode to access the Fileserver from PRAGMA 4. Use the external emulation mode for this purpose.

EXAMPLE OF AN INTERNAL EMULATION MODE PFM FILE

Define the file in the PRAGMA definition editor.

Then enter the following information:

FILE called AD3 ADDRESSES

The short name is AD3^ADDR
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 1
The number of indexes is 1
The significant length of index 1 is 20

1 AD NAME
2 AD CITY
3 AD COMPANY
4 AD STREET ADDRESS

LONGNAME

(AD3 ADDRESS) The name of the file in the PRAGMA program. It can be up to 31 characters long and may contain alphanumeric characters, nonalphanumeric characters and spaces. You may NOT use an underline.

SHORTNAME

(AD3^ADDR) The name that PRAGMA uses to find a PFM (or Btrieve) file in the operating system. When you create a new file in PRAGMA named LONGNAME, SHORTNAME is automatically generated for you, respecting the shortname naming convention. Shortname allows only alphanumeric characters and the underline character in the name and cannot be more than 8 characters long.

If you don't like the shortname generated for you, you may edit it at any time. But remember that the shortname and the name of the file on the operating system must always match, otherwise you get a "FILE NOT FOUND" error. If you change a shortname, remember to immediately change the name of the file on the operating system as well, assuming you already have such a file there.

BTRIEVE OPEN MODE

Applies only when using Btrieve files. It lets you choose if you want to open the Btrieve file in SAFE or FAST mode. The SAFE mode is the default, and is indicated by a 0 (zero). The FAST mode is obtained by inserting a -1. But be careful, depending on the operating system and the available memory, there is a maximum number of FAST Btrieve files that can be opened at the same time. Under DOS the maximum number is between 15 and 20.

PFM UNIT SIZE

Applies only when using PFM files. When converting an application from PRAGMA 3, the PFM unit size is calculated during the conversion.

MOCK FLAG

Tells the filemanager in what mode to operate. The PRAGMA 3 internal file emulation mode is 1.

NUMBER OF INDEXES

Must be set to 1.

SIGNIFICANT LENGTH OF INDEX

The length used by PRAGMA to compare when indexing. A significant
length of index has to be supplied. When converting an application
from PRAGMA 3 the default is 16.

After the header of the file definition come the nouns that are part of the file definition.

NOUNS

There is NO index selection noun in the file definition, as there is only ONE possible index. There is not necessarily a reference noun in the file definition, as the reference is ALWAYS given in the file command.

Duplicate references are not allowed.

You may of course add any noun you wish to complete your file record.

CREATING AN INTERNAL EMULATION MODE FILE

To create an internal emulation mode file when you are using PFM files, invoke the verb CREATE PFM FILE (CPF) and enter the name of the file.

For Btrieve you must create a description file with a text editor and use BUTIL to create the empty file.

If you are converting from PRAGMA 3 the file descriptions and the files are automatically created for you.

USING AN INTERNAL EMULATION MODE FILE

The usage of the three filemanagers is the same as when using internal file manager of PRAGMA 3. Even PRAGMA's Fileserver can be used in this mode, with a few restrictions. Most important, DELETE ALL does not work with Fileserver.

You do not check the FILE STATUS or the EXTERNAL ECHO. At the end of a GET NEXT your verb automatically returns, and so on. Your verbs would think that they are still running with the internal filemanager of PRAGMA 3. PRAGMA bridges the difference between what your program expects and what the file manager demands.

Important! If you are using numerical references, you MUST have a statement in the PRAGMA.DES file saying PFM NUMERIC REFS = YES.

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Native Mode
File Manager - Fileutil
File Manager - Butil
File Manager - Description File

File Manager - Mode 2 Operation

View Topic

PRAGMA 3 EXTERNAL EMULATION MODE

This mode is very similar to the PRAGMA 3 internal emulation mode.

The PRAGMA 3 external emulation mode can be used with either PFM or PRAGMA Fileserver as filemanager. With the simple limitation of not fully supporting numeric references, you can also use Btrieve.

This operating mode is automatically chosen when converting a PRAGMA 3 application for the PRAGMA 3 external files. As the name implies, this operating mode closely emulates the way PRAGMA 3 handles external files. That means that all the restrictions found in PRAGMA 3 and in the external files will apply.

This mode is the suggested mode to access the PRAGMA Fileserver from a PRAGMA 4 application.

EXAMPLE OF AN EXTERNAL EMULATION MODE FILESERVER FILE

Define the file in the PRAGMA definition editor and you will be prompted. Then enter the following information:

FILE called AD4 ADDRESSES

The short name is AD4^ADDR
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 2
The number of indexes is 1
The significant length of index 1 is 20

1 AD NAME
2 AD CITY
3 AD COMPANY
4 AD STREET ADDRESS

LONGNAME

(AD4 ADDRESS) The name of the file in the PRAGMA program. It can be up to 31 characters long and may contain alphanumeric characters, nonalphanumeric characters and spaces. You may NOT use an underline.

SHORTNAME

(AD4^ADDR) is the name that PRAGMA uses to find a PFM (or Btrieve) file in the operating system. When you create a new file in PRAGMA named LONGNAME, SHORTNAME is automatically generated for you, respecting the shortname naming convention. Shortname allows only alphanumeric characters and the underline character in the name and cannot be more than 8 characters long.

If you don't like the shortname generated for you, you may edit it at any time. But remember that the shortname and the name of the file on the operating system must always match, otherwise you get a "FILE NOT FOUND" error. If you change a shortname, remember to immediately change the name of the file on the operating system as well, assuming you already have such a file there.

BTRIEVE OPEN MODE

Applies only when using Btrieve files. It lets you choose if you want to open the Btrieve file in SAFE or FAST mode. The SAFE mode is the default, and is indicated by a 0 (zero). The FAST mode is obtained by inserting a -1. But be careful, depending on the operating system and available memory there is a maximum number of FAST Btrieve files that can be opened at the same time. Under DOS the maximum number is between 15 and 20.

PFM UNIT SIZE

Applies only when using PFM files.

MOCK FLAG

It tells the filemanager in what mode to operate. The PRAGMA 3 external file emulation mode is 2.

NUMBER OF INDEXES

Must be set to 1.

SIGNIFICANT LENGTH OF INDEX

Is the length used by PRAGMA to compare when indexing. Asignificant length of index has to be supplied. When converting an application from PRAGMA 3 the default is 18.

After the header of the file definition come the nouns that are part of the file definition.

NOUNS

There is NO index selection noun in the file definition, as there is only ONE possible index. The reference noun will not necessarily be in the file definition, as the reference is ALWAYS given in the file command.

Duplicate references are not allowed.

You may of course add any noun you wish to complete your file record.

CREATING AN EXTERNAL EMULATION MODE FILE

If you are using the PRAGMA Fileserver you must define the file on the Fileserver.

If you are using PFM files you invoke the verb CREATE PFM FILE (CPF) and enter the name of the file.

For Btrieve you must create a description file with a text editor and use BUTIL to create the empty file.

If you are converting from PRAGMA 3, the file descriptions are automatically created for you.

USING AN EXTERNAL EMULATION MODE FILE

The usage of the three filemanagers is the same as when using the external file manager of PRAGMA 3.

You MUST always check the FILE STATUS or the EXTERNAL ECHO.

Important! If you are using numerical references you MUST have a statement in the PRAGMA.DES file saying PFM NUMERIC REFS = YES.

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Native Mode
File Manager - Fileutil
File Manager - Butil
File Manager - Description File

File Manager - Native Mode

View Topic

FILE MANAGER - PRAGMA NATIVE FILE MODE

DEFINING A NATIVE PFM FILE

Before you can use a file when programming in PRAGMA you must define it and create, thereby, an empty file.

A file contains records, and each record has a certain number of nouns. Besides deciding on how many nouns you want, you also must decide how you want to access the file. This will determine how many indexes you will give that file. An index is the access path to a file.

For example, an address file can have four indexes:

Sequential number,
name,
company
city.

This lets you retrieve your records by number, name, company or city.

Number 123

Name Smith Joe
Company ACME Computers
Address 77 Hard Disk Drive
City Santa Clara
State CA

You must also decide the significant length of each reference. A reference is the noun value used when searching an index. The significant length is what PRAGMA will use to compare the references. A reference noun can be longer than its significant length. In that case PRAGMA will use only the significant length portion to compare the values.

You are not allowed to have duplicate references in a file.

So in order to accommodate all the various Joe Smiths you will have to make each one unique by adding something to his name. In our example above we can JOIN to the name (Smith) the number of the record. Since we want each record to have a different number anyway, this will ensure that each Mr. Smith will have its own, unique reference.

NUMBER NAME NAME REFERENCE

23 Smith Joe Smith Joe23
46 Smith Joe Smith Joe46
123 Smith Joe Smith Joe123

The same will have to be done with the company and city name.

To define a file in PRAGMA you type the word FILE (or the abbreviation FL) at START in the definition editor.

Continuing with our example, you will be prompted and then will have to enter the following information:

FILE called AD ADDRESS

The short name is AD^ADDRE
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 16
The number of indexes is 4
The significant length of index 1 is 8
The significant length of index 2 is 35
The significant length of index 3 is 35
The significant length of index 4 is 25
1 AD INDEX NOUN
2 AD NUMBER REFERENCE
3 AD NAME REFERENCE
4 AD COMPANY REFERENCE
5 AD CITY REFERENCE
6 AD NAME
7 AD COMPANY
8 AD CITY
9 COMMENT you may add more nouns if you want.
10 AD STREET ADDRESS
11 AD STATE

LONGNAME

(AD ADDRESS) The name of the file in the PRAGMA program. It can be up to 31 characters long and may contain alphanumeric characters, nonalphanumeric characters and spaces. You may NOT use an underline.

SHORTNAME

(AD^ADDRE) The name that PRAGMA uses to find a PFM file in the operating system. When you create a new file in PRAGMA named LONGNAME, SHORTNAME is automatically generated for you, respecting the shortname naming convention. Shortname allows only alphanumeric characters and the underline character in the name and cannot be more than 8 characters long. In our example, the space was changed to an underline (DOS does not allow spaces inside a filename) and the length was truncated to 8 characters.

If you don't like the shortname you may edit it any time you like. But remember that the shortname and the name of the file on the operating system must always match, otherwise you get a "FILE NOT FOUND" error. If you already have a file on the operating system, immediately also change its name.

BTRIEVE OPEN MODE

Does not apply for this mode.

PFM UNIT SIZE

By default the PFM unit size is 256. You may change it to any necessary value, within the limitations and recommendations described in the section on Fileutil.

If, when defining a PFM size you get an error, you more than likely must use a larger unit size.

MOCK FLAG

Tells the filemanager in what mode to operate. The default is the PFM native mode, mode 16.

NUMBER OF INDEXES

The number of indexes that your file will contain.

SIGNIFICANT LENGTH OF INDEX

The length used by PRAGMA to compare when indexing.

A significant length of index has to be supplied for every index.

A numeric reference must have a length of eight or longer, otherwise the numbers will not be compared correctly.

When you join nouns to obtain a unique reference, you must take the total length into account.

After having completed the header of the file definition you must enter the nouns that are part of the file definition.

AD INDEX NOUN

Immediately following the file header you MUST enter the index selection noun. This noun will tell the PFM filemanager which index to use when looking for a record. The index selection noun must contain a number.

Computers don't always have to be logical. So to retrieve a record with index number 1 copy a zero to the index selection noun. To retrieve a record with the index number 2 you copy a 1 to the index selection noun and so on.

Before you perform ANY file access in your program, ask yourself whether the index selection noun is set correctly. Better reinitialize it once again. An index noun with the wrong value can be a very difficult bug to trace in your application.

REFERENCE NOUNS

The file definition MUST contain the reference nouns after the index selection noun. They can be of any length you want, since the filemanager will automatically pad to the significant length if necessary. But they MUST be unique. No duplicate references allowed, ever.

To continue with our example, we want every record to have its own number, so AD NUMBER REFERENCE will not pose a problem. But AD NAME might, due to the proliferation of Smiths or Johnsons. So in your program you must JOIN AD NAME in front of AD NUMBER REFERENCE and put the result into AD NAME REFERENCE. AD NAME REFERENCE will be your reference and will never have a duplicate, regardless of how many Smiths populate your address book.

Please notice that the significant length of index 2 is 35. This is because we expect the name to have a maximum length of 30, to which we add 5, the maximum expected length of a AD NUMBER when joined to AD NAME. When you join a number to anything, it becomes an expression. So if you know that your addresses will never exceed 99,999, your AD NUMBER as an expression will be a maximum of 5 characters long.

To avoid having to CUT your references when you are retrieving records, we suggest that you also save the noun AD NAME as it is in the file (line 6). You may use a few bytes more per record, but this is a small price to pay considering the gain in convenience and speed.

OTHER NOUNS

After the reference nouns (and the unjoined nouns that make up a reference, if you use them) you may of course add any noun you wish to complete your file record.

CREATING A NATIVE PFM FILE

After having defined a native PFM file as described above, you must now create the empty file.

To create the file you invoke the verb CREATE PFM FILE (CPF) and enter the name (LONGNAME) of the file.

Should a file or a description file with this name already exist on the operating system level, you will be warned. If you continue in spite of the warning the old file will be overwritten and any data that it may have contained will be lost.

Once you have created a PFM file in this way you MUST NOT modify the file header without recreating an empty file. The only exception to this is the SHORTNAME, as long as you manually change the name of the file on the operating system level.

Also do not change the nouns that make up the file definition unless you really know what you are doing.

USING A NATIVE PFM FILE

To enter new data into the file you do something like this:

10 COPY the value 0 to the noun AD INDEX NOUN
...
20 COPY the value 123 to the noun AD NUMBER REFERENCE
21 COPY the value "John Smith" to the noun AD NAME
22 JOIN the value AD NAME to the value AD NUMBER REFERENCE
23 COPY the value HEAD to the noun AD NAME REFERENCE
24 COPY the value "ACME Computers" to the noun AD COMPANY
25 JOIN the value AD COMPANY to the value AD NUMBER REFERENCE
25 COPY the value HEAD to the noun AD COMPANY REFERENCE
...
...
30 SAVE reference 0 in file AD ADDRESS
31 IF the value FILE STATUS "^" the value 0
...

It is very important that after every file operation you check the FILE STATUS to make sure that the operation was completed successfully. Somebody might have accidentally deleted your file on the operating system!

When saving a NEW record the value in the index selection noun is not important. But it MUST be initialized.

When saving a new record the value of the reference is not important since PRAGMA knows what are the references. You can enter anything, a 0 or "good morning".

To list all the addresses sorted by AD NAME you do something like this:

10 COPY the value 1 to the noun AD INDEX NOUN
11 BEGIN FIRST in file AD ADDRESS
12 LABEL this line with
LOOP
13 GET NEXT in file AD ADDRESS
14 IF the value FILE STATUS "=" the value 0
do
DISPLAY the value AD NAME
DISPLAY the value LINE FEED
else
RETURN
end
20 GO TO line labeled LOOP

If, instead, you want to list the addresses sorted by AD CITY, you simply COPY a 3 to the noun AD INDEX NOUN in line 10.

A quick way to list your index nouns is by running the standard verb LIST REFERENCE from the start message. LIST REFERENCE will list references in any desired index.

Important! If you are using numerical references you MUST have a statement in the PRAGMA.DES file saying PFM NUMERIC REFS = YES.

See also:

File Managers - Overview
File Managers - Operating Modes
File Manager - Btrieve Mode
File Manager - Fileutil

File Managers - Operating Modes

View Topic

PRAGMA FILE MANAGERS - OPERATING MODES

PRAGMA gives you a choice of three filemanagers: PFM, Btrieve and PRAGMA's Fileserver.

PFM, the PRAGMA File Manager is the filemanager of choice for PRAGMA. It is the most versatile and can be used on any operating system supported by PRAGMA.

Btrieve, the filemanager supplied by Novell has been optimized for use on a Novell network. Various tools are available for it by Novell, but it cannot be used on UNIX.

PRAGMA's Fileserver is a filemanager program that resides on a dedicated fileserver machine and that can be accessed by as many as 48 workstations.

These filemanagers can be accessed in various modes, depending on your needs or whether you are developing a new program or converting a PRAGMA 3 program to PRAGMA 4.

If you are new to PRAGMA 4 or are using PRAGMA 4 to write a new application, you only have to be concerned with the native PRAGMA mode of operation, mode 16. Or at the most you may want to explore Btrieve mode (mode 0). Whatever your needs, we suggest that you first become familiar with the PFM file manager used in native mode.

PRAGMA 4 NATIVE MODE (Mode 16)

This is the suggested mode of operation when you are writing a new application for PRAGMA 4 or if you are new to PRAGMA 4.

Can only be used by PFM.

Allows multiple references (indexes).
References can be of any length, that means that they need not be
padded.
Each reference must be unique. To obtain uniqueness you must JOIN
nouns together, in your verbs.
Segments are not supported.

Numeric references are supported, provided you have the statement
PFM NUMERIC REFS = YES in the PRAGMA.DES file.

You can create empty .PFM files automatically from within the PRAGMA editor.

BTRIEVE MODE (Mode 0)

This is the mode of operation if you want to use Btrieve files or are converting a PRAGMA 3 application that uses Btrieve as the file manager. It is also useful if you want to use PFM files with segments to avoid duplicates.

Can only be used by PFM or Btrieve.

Allows multiple references (indexes).
References must be of fixed length, that means that they must be
padded.
Each reference must be unique. To obtain uniqueness you can use
segments in the description file that describes the file.

Numeric references are supported by PFM, provided you have the
statement PFM NUMERIC REFS = YES in the PRAGMA.DES file.
For Btrieve numeric references are not supported.

You must create an empty .PFM or .BTR file by hand, by first creating
a description file, and then use the utility FILEUTIL or BUTIL.

PRAGMA 3 INTERNAL EMULATION MODE (Mode 1)

This mode is used when converting a PRAGMA 3 application with internal files to PRAGMA 4.

Can be used by PFM, Btrieve or Fileserver.

Allows only one reference (index).
References can be of variable length.
Each reference must be unique. To obtain uniqueness you must JOIN
nouns together in your verbs.

Numeric references are supported by PFM, provided you have the
statement PFM NUMERIC REFS = YES in the PRAGMA.DES file and
Fileserver. For Btrieve, numeric references are not supported.

The empty .PFM files are automatically created during the
conversion process.

Mode 1 operates exactly like PRAGMA 3 internal files, that is you
cannot check the external echo after file operations. Testing is
performed automatically by PRAGMA, and errors cause the program to
abort.

PRAGMA 3 EXTERNAL EMULATION MODE (Mode 2)

This mode is used when converting a PRAGMA 3 application that uses Fileserver to PRAGMA 4 or if you want to access the Fileserver from a PRAGMA 4 program.

Can be used by PFM, Btrieve or Fileserver.

Allows only one reference.
References can be of variable length.
Each reference must be unique. To obtain uniqueness you must JOIN
nouns together in your verbs.

Numeric references are supported by PFM, provided you have the
statement PFM NUMERIC REFS = YES in the PRAGMA.DES file and
Fileserver. For Btrieve, numeric references are not supported.

The empty .PFM files are automatically created during the
conversion process.

Mode 2 operates exactly like PRAGMA 3 external files, that is you
have to check the external echo after file operations.

See also:

File Managers - Overview
File Manager - Native Mode
File Manager - Btrieve Mode

File Managers - Overview

View Topic

PRAGMA FILE MANAGERS - OVERVIEW

PRAGMA gives you a choice of three file managers:

PFM (PRAGMA File Manager)
Btrieve Files
PRAGMA Fileserver

The PRAGMA language has two completely separate sets of verbs to access a database. They are commonly referred to as "internal" and "external", terminology leftover from earlier days when it was descriptive of file location. Now it simply refers to what file words are being used to access a file. Internal and external locations have become more arbitrary. External refers to file words which have external as the first word of their name (e.g., EXTERNAL GET, EXTERNAL SAVE, etc.) internal refers to the rest (e.g., GET, SAVE, etc.).

PRAGMA File Manager files, Btrieve files and PRAGMA Fileserver can be addressed by both internal and external words.

The file managers to use are set by statements in PRAGMA.DES, and you can simply edit this text file to switch from one file manager to another, with some restrictions.

PRAGMA FILE MANAGER

The PRAGMA File Manager (PFM) is the file manager of choice for PRAGMA. There is only one version of it and it works in single user, multi-user, and network configurations without change under all the operating systems it supports. It is written entirely in the C language and this gives it portability to a large range of machines.

It is intended for use with PRAGMA under any of the operating systems supported by that product (DOS, OS/2, UNIX and LANs on these operating systems).

PFM supports an unlimited number of indexes, that is each file can be assigned different references or access paths. The maximum size of a PFM record is 64 K.

Practically, there is no limit to the size of a PFM file.

There is no limit inside PFM to the number of files that can be open at the same time. The operating system may, however, have such limitations.

The speed/safety factor of PFM is different from that of Btrieve. In general, it is not as safe as Btrieve SAFE mode, and not as fast as Btrieve FAST mode: it is somewhere in the middle. If you want safety, you must use a U.P.S.; if you want speed, use disk buffering that does NOT have write-through (write-through is a technical term describing the action of writing to disk any modified file data IMMEDIATELY, instead of holding it in cache memory as long as possible without writing it to disk. DOS has a write-through buffering scheme, Xenix does not. Write-through is safer, but generally slower.). The Norton cache program for DOS, or some other disk caching program can be used for this purpose.

BTRIEVE

Btrieve is a file manager supplied by Novell and can be used as the file manager for PRAGMA under DOS and OS/2.

Btrieve is written in Intel assembler code, and cannot be ported to non-Intel architecture. It can only be used for DOS and OS/2. There are no UNIX versions available of Btrieve.

It has the ability to control a maximum of 24 indexes. The field sizes of Btrieve records do not have to be specified except for the references. The maximum size of a Btrieve record is 64 K.

Btrieve can be run in two ways: SAFE or FAST. When running in safe mode Btrieve always keeps a backup of the record being written in so that even if there is an accidental power failure no data gets corrupted. When running in FAST mode there is a limit on how many files can be open at the same time.

A great number of utilities can be purchased for Btrieve and it is particularly suited to operate with Novell networks.

Btrieve is a separate program from PRAGMA. It must be loaded into memory under DOS and be part of the dynamic link library under OS/2.

When running in fast mode, Btrieve is a little bit faster than PFM (but there is a limit on the number of open files); while when running in safe mode, Btrieve is slower than PFM when writing to a file (and there is no limit on the number of open files).

FILESERVER

PRAGMA Fileserver is a file manager program that resides on a dedicated fileserver machine. It can be accessed by as many as 48 workstations.

Fileserver can be run on any IBM AT or 100% compatible using DOS 4.01. Serial interfaces provide the link between the Fileserver and the workstations making the entire system highly cost effective for its power.

Fileserver can be accessed by PRAGMA running under DOS and UNIX.

See also:

File Managers - Operating Modes

Fileutil

View Topic

FILEUTIL

Fileutil is a PRAGMA utility for PFM files that performs the following functions:

Validation of PFM files

Statistics of PFM files

Creation of new PFM files

Viewing of PFM files

Fileutil can be started like a regular program and all its functions can be accessed through a menu and by prompts. This is the easiest way of using Fileutil and is most useful when, for instance, you want to quickly validate a file or create a new one.

Another way to access the functions of Fileutil is to start the program with the appropriate parameters from the command prompt of the operating system. This feature is most useful if you have to repeatedly validate a great number of files since you can write batch files to automate this chore for you.

The results of the validation are always written to the PRAGMA.LOG file and if desired, can also be printed.

The DOS version of Fileutil can be run under Windows.

WARNING You can use Fileutil only with PFM files of PRAGMA 4 version 4.21 and higher.

INSTALLING FILEUTIL

Fileutil is like a compiled PRAGMA program and therefore requires the same environment as PRAGMA.

The easiest way to use Fileutil is to put it in the same directory as PRAGMA, and if PRAGMA works, Fileutil will also work.

RUNNING FILEUTIL

To run Fileutil in menu mode simply type Fileutil at the operating system prompt.

To run Fileutil no security device is needed.

The instructions on how to run Fileutil with command line parameters is given in the sections that deal with the various options.

PRAGMA LOG

Every time you start Fileutil an entry is made to the PRAGMA.LOG file stating at which time it started. Likewise, when you exit Fileutil an entry is made stating at which time it ended. If a start time does not have an end time, it means that Fileutil terminated in a nonstandard way.

Fileutil creates PRAGMA.LOG if it does not exist or appends to it if it does. Make sure to periodically delete this file, otherwise it can grow to a monstrous size.

The results of a validation are always written to the PRAGMA.LOG file.

If you want to change the name of the log file Fileutil writes to, you must edit the option LOG FILE NAME in PRAGMA.DES. The default name PRAGMA.LOG can be changed to any legal file name.

To disable logging, put no file name to the option LOG FILE NAME. But don't forget the space after the equal sign if you edit PRAGMA.DES manually.

PRINTING
You have the option to print the results of the validation.

To enable printing you must have a valid entry in the PRINTER option of PRAGMA.DES.

THE DESCRIPTION FILE PRAGMA DES

Fileutil utilizes the file PRAGMA.DES for some of its parameters such as the name of the log file or the printer to print to.

Should you for any reason need a different description file than PRAGMA.DES (if you want, for example, write the results of a validation to a different log file than PRAGMA.LOG, you may make a description file exclusively for Fileutil by creating a new description file and calling it FILEUTIL.DES.

The following parameters are used by Fileutil:

PRINTER
LOG FILE

See also:

Fileutil - Validation
Fileutil - Validation Errors
Fileutil - Statistics
Fileutil - File Creation
Fileutil - File View
File Manager - Fileutil

Fileutil - File Creation

View Topic

Fileutil - File View

View Topic

Fileutil - Statistics

View Topic

FILEUTIL - STATISTICS

The file statistics program will analyze a file and display the following items:

Pagesize

The size of a page for that file.

Number of records

The number of records found in the file. This number should be the same as when you do a LIST REFERENCES of the file.

Number of nouns

The number of nouns that are in a record.

Be aware that this number may be misleading. There is no real way for the program to know for certain how many nouns are in a record. This information is not part of the controls and is derived by counting how many nouns are in the first record. Other records may have a different number of nouns in them, which may happen when one alters a file and adds nouns to it. Newer records may therefore have more nouns than older ones.

Number of indexes

The number of indexes for that file.

Number of segments

The number of segments for that file.

Variable length references

Whether a file has variable length references or not.

Filetype

A PFM file can contain data or PRAGMA vocabulary.

Segments

The number of indexes for that file.

Warning You may crash when analyzing a file with corrupted records or controls. Should this happen, proceed to the validation of the file to find out what is wrong with it.

Displaying Statistics from the Menu

Choose the option Statistics from the main menu. At the prompt enter the name of the file and its extension. If you wish you may add a path to the filename. Wildcard characters (* and ?) are not allowed.

Displaying Statistics from the Command Line

At the operating system prompt type the following command:

FILEUTIL -STAT FILENAME.PFM

-STAT
The parameter -STAT will tell Fileutil to start the program bypassing the menu and to go directly to the file statistics program.

FILENAME.PFM
Name and suffix of the file to analyze. If you wish you may add a path to the filename. Wildcard characters (* and ?) are not allowed.

See also:

Fileutil
Fileutil - Validation
Fileutil - Validation Errors
Fileutil - File Creation
Fileutil - File View
File Manager - Fileutil

Fileutil - Validation

View Topic

FILEUTIL - VALIDATION

The PFM file validation program will perform a validation of the following items of a PFM file:

File control page

Index pages

Data pages

Bitmaps

You can validate both data files and the PRAGMA Vocab file.

Validating from the Menu

Choose the option Validation from the main menu. At the prompt enter the name of the file and its extension. If you wish you may add a path to the filename. Wildcard characters (* and ?) are not allowed.

Fileutil will immediately start the validation and display the results on the screen. At the end of the validation the program will tell you if any errors were encountered.

If any errors were found they will be displayed in the error window.

The results of the various validations and the encountered errors (if any) will also be automatically written to the PRAGMA.LOG file.

Validating from the Command Line

The complete command line for the validation is:

FILEUTIL -VALIDATE FILENAME.PFM -PRINT -CONTINUE

-VALIDATE
The parameter -VALIDATE will tell Fileutil to start the program bypassing the menu and to go directly to the validation program.

FILENAME.PFM
Name and suffix of the file to validate. If you wish you may add a path to the filename. Wildcard characters (* and ?) are not allowed.

-PRINT
This optional parameter will also print the results of the validation on your printer. Before printing make sure to have enabled printing in PRAGMA.DES or FILEUTIL.DES.

-CONTINUE
This optional parameter will not stop the program after the validation of a file. Also, when the -PRINT option has been chosen, the printer will not issue a form feed at the end of a validation. This option enables you to validate a number of files automatically by writing a batch file.

Validating with a Batch File

If you repeatedly have to validate a great number of files (as you always should, especially before making a backup) you should write one or more batch files to automate the procedure.

The following example validates all the files used by PRAGMA itself and the VOCAB.

VALIDATE.BAT

ECHO OFF

FILEUTIL -validate PRMSG.PFM -print -continue
FILEUTIL -validate PRSTD.PFM -print -continue
FILEUTIL -validate PRAREF.PFM -print -continue
FILEUTIL -validate PRAREF2.PFM -print -continue
FILEUTIL -validate PRADES.PFM -print -continue
FILEUTIL -validate PRAPRINT.PFM -print -continue
FILEUTIL -validate SCREENS.PFM -print -continue
FILEUTIL -validate PRVOCAB.PFM -print

The result of the validation will also go to the printer. The results will be printed one after the other. Only after the validation of the VOCAB will the printer issue a form feed.

The program will come to an end by displaying the VOCAB validation screen. To go back to the operating system simply hit the <ESC> key.

If you want to terminate the validation with the screen displaying the operating system prompt (or ringing the bell or whatever your heart desires) add the -continue parameter to the last validation line. But then you must provide the form feed command to the printer.

See also:

Fileutil
Fileutil - Validation Errors
Fileutil - Statistics
Fileutil - File Creation
Fileutil - File View
File Manager - Fileutil

Fileutil - Validation Errors

View Topic

FILEUTIL - VALIDATION ERRORS

Validation Errors
If any errors are encountered during the validation, the program displays them on the screen in the error window and writes them to the PRAGMA.LOG file and, if you wish, to the printer.

Each error is displayed or printed on one line.

Each error, besides the error number, will also display up to four parameters, called P1, P2, P3 and P4. All the numbers displayed for the P1 to P4 parameters are in hexadecimal.

The following message numbers correspond to these types of errors:

Error numbers Error

1 to 99 File control page errors

101 to 199 Index page errors

201 to 299 Data page errors

401 to 499 Bitmap validation errors

501 to 599 Record errors

File Control Page Errors

Error #

1 The pagesize is less then the minimum-space needed for
storing the control information (92 bytes).
P1 = Size of the page in the file
P2 = Minimum size needed for the control page

2 This version of FILEUTIL.EXE cannot validate this file.
P1 = Version of the file
P2 = Version of FILEUTIL.EXE

3 The unit datasize is not of the right size.
P1 = Size in the file
P2 = Size calculated

4 The number of bits per page is not of the right size.
P1 = Number of bits in the file
P2 = Number of bits calculated

5 The number of bitmap pages is 0, but the pointer to the
incomplete bitmap page is not 0.
P1 = Pointer to the bitmap page stored in the file

6 The number of bitmap pages is 0, but the pointer to the
offset in page 0 is not 0.
P1 = pointer to offset in the bitmap page

7 The pointer to the incomplete bitmap page is higher than
the number of bitmap pages.
P1 = Pointer to the bitmap page in the file
P2 = Number of bitmap pages in the file

8 The pointer to the first free bit in the bitmap page
points outside of the bitmap page.
P1 = Pointer to the free bit
P2 = Number of bits in one bitmap page

9 The number of records is 0, but the number of bitmap pages
is not 0.
P1 = Number of bitmap pages in the file

10 The number of bitmap pages is less then the calculated
number of bitmaps needed to reflect all units of the file.
P1 = Number of bitmap pages in the file
P2 = Calculated number of needed bitmap pages

11 The count of index pages is 0, but the count of data pages
in the file is higher than 0.
P1 = Count of data pages in the file

12 The count of index pages is not 0, but the count of
data pages is 0.
P1 = Count of data pages in file

13 The count of index pages in the file is not less than
the count of data pages in the file.
P1 = Count of index pages in file
P2 = Count of data pages in file

14 The count of records in the file is 0, but the count of
index pages is not 0.
P1 = Count of index pages in file

15 The count of records in the file is not 0, but the count
of index pages is 0.
P1 = Count of index pages in file

16 The count of data pages in the file is less than the count
of records in the file.
P1 = Count of data pages in file
P2 = Count of records in the file

17 The count of index pages is bigger than the difference
between the count of data pages and the count of records.
P1 = Count of index pages in file
P2 = Value of the difference

18 The count of indexes in the file is 0.

19 The count of segments in the file is 0.

20 The count of segments is less then the count of indexes.
P1 = Count of segments in the file
P2 = Count of indexes in the file

21 The page size is not big enough to store all data of the
control page.
P1 = Page size in the file
P2 = Needed page size

22 The count of records in the file is 0, but the pointer
to the top level of the index is not 0.
P1 = Pointer to top level for the index
P2 = 0
P3 = Number of the index checked

23 The count of records in the file is 0, but the count of
the index level for this index is not 0.
P1 = Count of index level for the index
P2 = 0
P3 = Number of the index checked

24 The count of records in the file is not 0, but the pointer
to the top level of the index is 0.
P1 = 0
P2 = 0
P3 = Number of the index checked

25 The count of records in the file is not 0, but the count of
index levels for this index is 0.
P1 = 0
P2 = 0
P3 = Number of the index checked

26 The count of already used segments is not the same as the
value in the index.
P1 = Value in the index
P2 = Calculated number of used segments
P3 = Number of the index checked

27 The count of already used segments plus the needed number of
segments for this index is bigger then the total number of
segments in the file.
P1 = The sum of segments inclusive this index
P2 = Number of segments in the file
P3 = Number of the index checked

28 The start of the segment for this index exceeds the size
of the fixed part of the record.
P1 = Start of the segment
P2 = Size of the fixed part in the file
P3 = Number of the segment checked

29 The length of the segment is 0.
P1 = 0
P2 = 0
P3 = Number of the segment checked

30 The fixed part of the record is less then the end of the
last segment.
P1 = End of the segment
P2 = Size of the fixed part
P3 = Number of the segment checked

31 The calculated size of the index is not equal to the
value in the index part of the file.
P1 = Calculated size of the index size
P2 = Value of the index part
P3 = Number of the index checked

32 The maximum size of the biggest index is less than the
calculated maximum size of the index.
P1 = Calculated maximum size
P2 = Value of the maximum size in the control page
P3 = Number of the index checked

33 The count of index entries in one page is not equal to the
value in the control page of the file.
P1 = Value of the control page
P2 = Calculated number of entries
P3 = Number of the index checked

34 The size of the fixed part of the record is not equal to
the calculated fixed size of the record.
P1 = Calculated fixed size
P2 = Value in the control page of the file

35 The calculated maximum size of all indexes is not equal to
the value in the control page of the file.
P1 = Calculated maximum size of indexes
P2 = Value in the control page of the file

Index Page Errors
These errors are found without checking the data pages.

Error #

101 The level of the read index page does not have the expected
level.
P1 = Index level of page
P2 = Expected level
P3 = Number of the index checked

102 The value for the number of entries of the read index page is 0.
P1 = 0
P2 = 0
P3 = Number of the index checked
P4 = Number of index page

103 The value for number of entries of the read index page is
bigger than the maximum number of indexes for this index.
P1 = Value in the index page
P2 = Maximum number of entries for this index
P3 = Number of the index checked
P4 = Number of the index page

104 The page of the top level in this index shows a value for
the forward pointer, which is not 0.
P1 = Value for the forward pointer
P2 = 0
P3 = Number of the index checked
P4 = Number of the index page

105 The page of the top level in this index shows a value for
the backward pointer, which is not 0.
P1 = Value for the backward pointer
P2 = 0
P3 = Number of the index checked
P4 = Number of the index page

106 The number of entries in the top level page of this index
is less than 2 and the record count is more than 1.
P1 = Number of entries in this page
P2 = 1
P3 = Number of the indexes checked
P4 = Number of the index page

107 The data part for the first entry of this index level is
not equal to the expected data part of the previous level.
P1 = Number of index pages in the previous level
P2 = Number of entries in the previous level
P3 = Number of index checked
P4 = Number of index page

108 The number of valid entries in the index page is bigger than
the value in the header of the index page.
P1 = Unit number pointed to
P2 = 0
P3 = Number of the entry in the index page
P4 = Number of the index page

109 The entry does not point to a page (data or index).
P1 = 0
P2 = 0
P3 = Number of the entry in the index page
P4 = Number of the index page

110 The data part of this entry is not bigger than the data part
of the previous entry.
P1 = Number of the entry
P2 = Number of the index checked
P3 = Number of the index page

Data Page Errors
These errors are found inspecting the units of the records following the index chain. The data itself is not checked.

Error #

201 In the first index page of the index level 0 the forward
pointer is set to 0.
P1 = 0
P2 = 0
P3 = Number of the indexes checked
P4 = Number of the index page

202 The pointer of the entry in the index page points to 0.
P1 = 0
P2 = 0
P3 = Number of the index page
P4 = Number of the entries in the index page

203 In the first data page of the record the
backward pointer not set to 0.
P1 = Backward pointer of the data page
P2 = 0
P3 = Number of the indexes checked
P4 = Number of the data page

204 In the first data page of the record the total length
of the record is set to 0.
P1 = 0
P2 = 0
P3 = Number of the data page

205 In the first data page of the record the total length
of the record is smaller than the fixed part of the record.
P1 = Length of the record
P2 = Length of the fixed part of the record
P3 = Number of the data page

206 In the first data page of a record that is bigger than
one page, the forward pointer is set to 0.
P1 = 0
P2 = 0
P3 = Number of the data page

207 In the next data page the backward pointer does not point to the
previous data page.
P1 = Number of the previous data page
P2 = Value of the backward pointer of this data page
P3 = Number of the data page

208 The accumulated length of the record fields is not equal
to the total length in the first data page of this record.
P1 = Accumulated length of all fields
P2 = Total length of the record in the first data page
P3 = Number of the first data page of this record

209 The forward pointer of this data page points to 0, but
the record is not finished.
P1 = Forward pointer of this data page
P2 = 0
P3 = Number of the first data page of this record
P4 = Number of this data page

210 In the data page of a record which is shorter than one
data page, the forward pointer is not set to 0.
P1 = Value of the forward pointer
P2 = 0
P3 = Number of this data page

211 The count of seen valid records is not equal to
the count of records in the control page of this file.
P1 = Count of records in the control page
P2 = Count of valid records
P3 = Number of the index

Bitmap Validation Errors
This validation marks all used units in one separate bitmap. If the unit to be set as used is already marked as used, an error is generated.

When all the units of the file have been checked, the stored bitmap will be compared to this newly created bitmap.

Error #

401 The bit in the bitmap, created during validation of the index pages
and data pages is not equal to the bitmap stored in the file.
P1 = Number of data page or index page
P2 = Number of the bitmappage
P3 = Byte position in the bitmap page
P4 = Bit position in the byte

402 The unit to be marked as used is already marked.
P1 = Number of data page or index page

Record Errors
This validation checks all the records in the file.

One record is read into a buffer and then checks all nouns and noun types. It also determines whether the last noun exceeds the length of the record.

Error #

501 The field type of the field is not numeric and not string.
P1 = Number of the first data page
P2 = Type of the field
P3 = Offset in the record

502 The length of a numeric field is 0.
P1 = Number of the first data page
P2 = Type of the field
P3 = Offset in the record

503 The total length of the record is not equal to the length
of the record from the first data page of the record.
P1 = Number of the first data page
P2 = Type of the field
P3 = Offset in the record
P4 = Length of the record of the first data page

504 A verb or file definition points to a unit that is not a valid
vocab item.
P1 = Unit number of verb or file definition
P2 = Definition element number
P3 = Unit number of non valid vocab item

See also:

Fileutil - Validation
Fileutil - Statistics
Fileutil - File Creation
Fileutil - File View
File Manager - Fileutil

Getting Ready for the Tutorial

View Topic

Goliath to PRAGMA 4 Conversion

View Topic

GOLIATH TO PRAGMA 4 CONVERSION

Old Goliath applications stored their data in 7 bit format. This was a problem in many European countries that needed special characters in their languages. Logical solved that problem at the time by letting each country add the necessary characters to the lower ASCII set and providing translatio programs. So much for history.

If a user is employing an old Goliath with a translating program he will find that upon converting the data stored in the Goliath to PFM or Btrieve files that he cannot use the old translating program anymore and will find starnge characters in his data, like a "[" instead of some character peculiar to his language.

PRAGMA 4 can translate between the IBM character set and these other character sets when communicating with a Goliath. By default, no translation takes place.

This ability is available with version 4.21.12 or higher of PRAGMA 4.

The desired translation tables must be prepared in a binary file. Any binary file editor, like the Norton Utilities, may be used for this purpose. This file may have any desired name. As an example, the file CHARSET.US, found in the DOS88 release diskette of PRAGMA, may be used. This file performs no remapping (none is needed in the U.S.).

This file is not needed in the U.S. It is being supplied only as a starting point for your own customization. You may modify this file to fit the needs of your country, and then rename it appropriately.

The binary character set file contains both translation tables; the incoming and the outgoing. The inbound table occupies the first 256 bytes of the file; the outbound table occupies the next 256 bytes. Each table is indexed by the byte to be translated, and the contents of that byte of the table is the translated value. For instance, if the byte to be translated is hexadecimal 54, you would get the byte at offset hex 54 from the appropriate table, and use its value as the translated character. The inbound table is used for data being received by PRAGMA. The outbound table is used for data being sent from PRAGMA. This translation affects fileserver communications ONLY.

When you translate a character, you must always translate both the incoming and the outgoing characters, even if you only want to get data from the Fileserver.

Use the line "CHARACTER SET FILE = filename" in PRAGMA.DES to tell PRAGMA what file contains the translation tables.

See also:

Converting ADAM Applications
Converting NL Applications

Installing PRAGMA on DOS

View Topic

INSTALLING PRAGMA ON DOS

PRAGMA comes on two diskettes. One called DOS LOGIC, contains all the necessary files to run and program in PRAGMA. The other, called DOS UTILITIES, necessary, for instance, to translate a PRAGMA application to the C language.

On your hard disk make a subdirectory called, for instance, PRAGMA. Call the directory anything you like, as long as you only use the lower ASCII character set. That means no � or �, for instance. Then copy the two executable files from the PRAGMA diskettes to this newly created subdirectory.

To save space the PRAGMA files have been compressed. To extract them simply type the name of the executable files in the subdirectory.

The DOS LOGIC diskette contains (after self-extraction) the following files:

PRAGMA.EXE
DOS4GW.EXE
COMIO.COM
PRAGMA.DES
PRAGMA.ICO
PRVOCAB.PFM
PRMSG.PFM
PRSTD.PFM
PRAREF.PFM
PRAREF2.PFM
PRADES.PFM
PRAPRINT.PFM
SCREENS.PFM
TERMINFO.LBS
WEMU387.386

PRAGMA.EXE
The PRAGMA Software Development System that lets you program and run PRAGMA applications .

DOS4GW.EXE
The DOS extender program that allows PRAGMA to run in protected mode.

COMIO.COM
Interrupt driven communication handler.

PRAGMA.DES
The text file that contains various parameters which are user definable.

PRAGMA.ICO
The file that contains the PRAGMA icon for Microsoft Windows.

PRVOCAB.PFM
The file that contains the user vocabulary in a compressed format. On the PRAGMA release diskette, the vocabulary is empty. All PFM files are compatible with any operating system supported by PRAGMA, that is, the DOS, OS/2 and UNIX versions are the same.

PRMSG.PFM
The file that contains all the messages of PRAGMA and PREDIT.

PRSTD.PFM
The file that contains all the standard names and abbreviations of the PRAGMA Software Development System.

PRAREF.PFM
The help file that contains the on-line explanations of all the standard words of the PRAGMA Software Development System. Each screen explains one standard word, giving only the essential facts.

PRAREF2.PFM
The second help file that contains lengthy, detailed explanations of the more complicated standard words and all the help texts like this one.

PRADES.PFM
The help file that contains the description of all the parameters of PRAGMA.DES for the online help.

PRAPRINT.PFM
The file that contains the print parameters for various printers. It is used by the online help.

SCREENS.PFM
The file that contains the screens made by the PRAGMA screen generator.

TERMINFO.LBS
A text file that describes the characteristics of the terminal. It is especially important for UNIX but it must also be available for DOS and OS/2. It is expected to be in the directory where PRAGMA is or you can put it into a subdirectory called \USR\LIB\TERMINFO. But be aware that if you install PRAGMA on more than one hard disk, you will have to put a \USR\LIB\TERMINFO subdirectory onto every hard disk that has PRAGMA.

WEMU387.386
A file only used if you want to run PRAGMA under Windows and experience startup problems .

The DOS UTILITY diskette contains (after self-extraction) the following files:

FILEUTIL.EXE
MAKE.EXE
PRA2PFM.EXE
PREDIT.EXE
SCRNCAP.EXE
PRAGMA.LIB
COMM.LIB
PREDIT.DES
PRVOCAB.DES
PREDIT.ICO
PRMSG2.PFM
FILE.H
NOUN.H
VERB.H
CHARSET.US

FILEUTIL.EXE
The utility to create new PFM files and validate them.

MAKE.EXE
The make utility used when compiling a PRAGMA application.

PRA2PFM.EXE
Translates the user vocabulary from the PRAGMA 3 format into PRAGMA 4 format. It reads user vocabulary from the PRVOCAB.000 file, reformats it and writes it to the PRVOCAB.PFM file. It also performs the file transfer from internal files to PFM files.

PREDIT.EXE
The PRAGMA message editor program.

SCRNCAP.EXE
A utility used when converting SAYWHAT screens to the PRAGMA format.

PRAGMA.LIB
The library that contains the code to compile your PRAGMA programs.

COMM.LIB
The library that contains additional code to compile your PRAGMA programs.

PREDIT.DES
The text file that contains various parameters for the message editor which are user definable.

PRVOCAB.DES
A textfile used in conjunction with FILEUTIL to create an empty PRVOCAB.PFM file.

PREDIT.ICO
The file that contains the PREDIT icon for Microsoft Windows.

PRMSG2.PFM
The file that is used by PREDIT to edit the messages.

FILE.H
NOUN.H
VERB.H
The include files used when compiling a PRAGMA application.

CHARSET.US
Translation table to translate from the old Goliath 7 bit character set.

See also:

Environment Configuration - DOS
Operating Systems Overview
Running PRAGMA on DOS
Running PRAGMA on NETWORKS

Installing PRAGMA on OS/2

View Topic

INSTALLING PRAGMA ON OS/2

The PRAGMA OS/2 diskette that you received contains all the necessary files to be able to program, run and translate a PRAGMA application to the C language.

On your computer's hard disk make a subdirectory called, for instance, PRAGMA. Then copy all the files from the OS2 subdirectory of the PRAGMA diskette to this newly created subdirectory.

The directory will contain the following files:

PRAGMA.EXE
FILEUTIL.EXE
PREDIT.EXE
PRAGMA.DES
PREDIT.DES
PRVOCAB.PFM
PRMSG.PFM
PRMSG2.PFM
PRSTD.PFM
PRAREF.PFM
PRAREF2.PFM
PRADES.PFM
PRAPRINT.PFM
SCREENS.PFM
TERMINFO.LBS
PRVOCAB.DES
BTRCALLS.DLL
PRAGMA.ICO
PREDIT.ICO

PRAGMA.EXE
The PRAGMA Software Development System that lets you program in PRAGMA.

FILEUTIL.EXE
The utility to create new PFM files. Although named the same, it is not the same program used for DOS.

PREDIT.EXE
The PRAGMA message editor program.

PRAGMA.DES
The text file that contains various parameters which are user definable.

PREDIT.DES
The text file that contains various parameters for the message editor which are user definable.

PRVOCAB.PFM
The file that contains the user vocabulary in a compressed format. On the PRAGMA release diskette, the vocabulary is empty. All PFM files are compatible with any operating system supported by PRAGMA, that is, the DOS, OS/2 and UNIX versions are the same.

PRMSG.PFM
The file that contains all the messages of the PRAGMA and PREDIT.

PRMSG2.PFM
A file that is used by PREDIT to edit the messages.

PRSTD.PFM
The file that contains all the standard names and abbreviations of the PRAGMA Software Development System.

PRAREF.PFM
The help file that contains the online explanations of all the standard words of the PRAGMA Software Development System. Each screen explains one standard word, giving only the essential facts.

PRAREF2.PFM
The second help file that contains lengthy, detailed explanations of the more complicated standard words and all the help texts like this one.

PRADES.PFM
The help file that contains the online explanations of all the parameters of PRAGMA.DES.

PRAPRINT.PFM
The file that contains the print parameters for various printers. It is used by the online help.

SCREENS.PFM
The file that contains the screens made by the PRAGMA screen generator.

TERMINFO.LBS
A text file that describes the characteristics of the terminal. It is especially important for UNIX but it must also be available for DOS and OS/2. It is expected to be in the directory where PRAGMA is or you can put it into a subdirectory called \USR\LIB\TERMINFO. But be aware that if you install PRAGMA on more than one hard disk, you will have to put a \USR\LIB\TERMINFO subdirectory onto every hard disk that has PRAGMA. The same file is used in all the operating systems supported by PRAGMA.

PRVOCAB.DES
A textfile used in conjunction with FILEUTIL to create an empty PRVOCAB.PFM file. The DOS and OS/2 versions are the same.

BTRCALLS.DLL
A dummy (empty) library, that is, not the real Btrieve library supplied by Novell. It is only needed if you do not use Btrieve. You must copy the dummy BTRCALLS.DLL file to the \OS2\DLL subdirectory. This is a subdirectory that OS/2 created that contains all the DLL files. You must do this because PRAGMA links to the Btrieve library and if it is not there, even if you are not using Btrieve, you cannot run a PRAGMA program.

If you plan to use Btrieve discard this file and substitute it with the real one that comes on your OS/2 Btrieve diskette supplied by Novell. Copy the file BTRCALLS.DLL from your OS/2 BTRIEVE diskette to the \OS2\DLL subdirectory.

PRAGMA.ICO
PREDIT.ICO
The files that contain the icons for the various programs.

See also:

Environment Configuration - OS/2
Operating Systems Overview
Running PRAGMA on OS/2
Running PRAGMA on NETWORKS

Installing PRAGMA on SCO UNIX

View Topic

INSTALLING PRAGMA ON SCO UNIX - INTERACTIVE UNIX

PRAGMA for SCO UNIX is on a single diskette created by the program tar ( tape file archiver). It can only be read by UNIX; you cannot use DOS DISKCOPY to copy it. If you wish to copy it, you must use the UNIX program diskcp.

This diskette works for SCO Xenix, the newer SCO UNIX and Interactive UNIX.

In order to install PRAGMA for UNIX, you must be logged in to the system as superuser (# prompt). This gives the installation process the permissions necessary to modify the files. You must also have the root directory as your current directory. This will be the case if you have logged in as root and done nothing else.

PRAGMA for SCO UNIX is installed by using the UNIX software installation program custom. The following description of custom applies only to SCO Xenix. In SCO UNIX custom appears to be different, but it is used in much the same way as Xenix.

Run the program custom by typing custom. It will give you a menu of packages. Option 4 is Add a Supported Product . Since PRAGMA for UNIX is not on the menu yet, you must choose this option, number 4. If you have already installed PRAGMA for UNIX, and you are either removing it, or converting to a newer version, PRAGMA for UNIX will appear in the menu; if this is the case, choose whatever the corresponding number is. If you choose option 4, Add a Supported Product, it will then ask you to insert disk 1 so it can read the product information from it. Do so.

After it reads the product information, it gives you a second menu. Choose option 1, Install One or More Packages. This will then list all of the available packages that are a part of this software release.

PRAGMA consists of the following different packages:

ALL PRAGMA for SCO Xenix/UNIX Complete

You may choose ALL to install the complete PRAGMA for SCO UNIX system on your machine. You would normally do this if you intended to use this machine for software development. You do not need to choose ALL if you only plan to run PRAGMA applications.

SYSTEM PRAGMA System Support Files

Regardless of whatever other packages you plan to install, this one is required in all cases because it contains the device driver for the security device, terminfo and the initialization script.

SYSUTIL PRAGMA System Utilities

This package is optional for end users. It contains the utilities FILEUTIL and doscopy and is useful when doing development work.

COMPILE PRAGMA Compiled Runtime System

This package is only needed to compile an application. It contains the PRAGMA library and the header files.

INTERP PRAGMA Software Development System

This package contains the PRAGMA interpreter executable file and the .PFM files. The .PFM files get put into the directory /usr/pragma, and you can then copy them from there to wherever you need them. This is the package you need to develop and run applications.

If disk space is not an issue, simply choose ALL. You can however be selective if you want to save a bit of disk space, or perhaps remove the temptation from users to use FILEUTIL and blow away something by accident. In any event it is important that SYSTEM always be installed.

custom also gives you the choice of listing the files that make up a package.

custom will ask you for your system type, whether it is SCO Xenix, SCO UNIX or Interactive UNIX. Type the appropriate answer.

After the SCO Xenix or SCO UNIX installation has completed without errors, you must exit custom by pressing "q" at the menu until you are back to the operating system (# prompt). At this point, you must reboot the system to load the new UNIX kernel into memory. Run shutdown to halt the system. Then, when the normal system shutdown message appears, press any key to reboot. You should never get any error during the installation. If you do and the program bails out, it will not have properly completed the installation. In this case, you have to start all over again.

The installation of Interactive UNIX using custom will produce an error at the end. But even though an error message is output, the system has been installed properly.

Another way to see all the files that make up a PRAGMA release and where they go, is by putting the release diskette into the floppy drive and typing tar tv.

The following files are put into a directory called usr/pragma:

PRVOCAB.PFM (empty)
PRVOCAB.DES
pragma.des
PRMSG.PFM
PRSTD.PFM
PRAREF.PFM,
PRAREF2.PFM
PRADES.PFM
PRAPRINT.PFM
SCREENS.PFM

IMPORTANT.

With SCO Xenix only, if you want to switch to a more recent version of PRAGMA you first have to delete all the files with custom. Then, always as a superuser, go to the /etc/perms directory and delete (rm) the file pragma.perms. Then go back to custom and start the whole installation of PRAGMA afresh.

WARNING.

This is one of the few times that you have to actually do something to a file as a superuser. Don't abuse your powers as superuser. You can get into trouble in a hurry, and most of the time, without even being warned. You will then have to reinstall the whole UNIX system from the beginning.

NOTE.

This entry is only intended to get you as far as the PRAGMA prompt in UNIX on the main console. More information can be found in different entries and of course, in the UNIX manuals.

INTERACTIVE UNIX

The same diskettes that are used to install PRAGMA on SCO UNIX can also be used to install PRAGMA on Interactive UNIX. Answer Interactive UNIX when prompted to choose system type.

The installation of Interactive UNIX using custom will produce an error at the end. But even though an error message is output, the system has been installed properly.

Interactive UNIX needs a serial type security device to run.

PRAGMA is actually an SCO Xenix program. An SCO UNIX program has a different format than a Xenix program, but is able to run a Xenix program. You will be able to run PRAGMA on non SCO UNIX only if it is able to run an SCO Xenix executable.

MANUAL UNIX INSTALLATION

Should you want to do a manual installation of PRAGMA you have to manually split the PRAGMA diskette into separate diskettes. First extract all of the PRAGMA diskette with tar to a clean directory. Two files, pragma.perms (containing text describing the available software packages) and the volume label file (which is empty) can be discarded. They are only needed for custom. Otherwise, the PRAGMA diskette is a normal tar diskette.

You can create new PRAGMA diskettes by using the command tar cv ./* ( tape file archiver, option create new tape, print each file name as processed). Make sure you use ./* which is a relative directory, not absolute. The newly created diskettes can then be installed with tar individually, without using custom.

After having installed all of the PRAGMA diskettes with tar the only thing left to do is to run the script init.pragma that modifies the kernel, so that PRAGMA will be allowed to read the parallel security block. The file init.pragma, is put by tar into the /tmp directory. No errors should ever be seen during this process.

If you are using the green serial blocks the kernel does NOT need to be modified. If you choose the Interactive system when running init.pragma, the kernel changes are skipped.

SERIAL SECURITY DEVICE

When using PRAGMA 4 on a UNIX system that is not SCO, you must use the serial security device. The parallel security device is not supported with non SCO UNIX. The serial device can also be used for machines running SCO UNIX. In that case there is no need to modify the kernel. To bypass the kernel modification choose Interactive UNIX when prompted to choose the system type.

To use a serial security device you must attach it to a serial port with a baud rate of 9600, 8 bits/character, no parity and the port must be DISABLED for login. In pragma.des you must put the line SECURITY = portname, where portname is the UNIX device name for the port (example /dev/tty1a), in order to tell PRAGMA where to look. The security device MUST have a port all to itself.

You must also give read and write permission for everybody for the port device node to which the serial block is connected. Usually this is found in the /dev directory and the name will be ttyxx.

See also:

Environment Configuration - DOS
Operating Systems Overview
Running PRAGMA on DOS
Running PRAGMA on NETWORKS

Learning About the Screen Generator

View Topic

LEARNING TO USE THE PRAGMA SCREEN GENERATOR

The following is a short introduction on how to use the PRAGMA screen generator. If you wish to practice with the screen generator while reading this tutorial, you can print these instructions on your printer. For more information on how to print the online help please consult the entry called Online Help and Reference of the main online help.

The screen generator is accessed through the PRAGMA online help. The online help is accessed by hitting the <F1> key whenever you are at the PRAGMA start prompt. Then open the UTILITIES menu and select Screen Generator.

The first screen that appears when entering the screen generator is its menu screen. Besides letting you save and retrieve screens from the SCREENS.PFM file, the menus let you perform all the tasks that you can do with the shortcut keys while editing a screen. Although performing some of these tasks through the menus is not very efficient, it has the advantage of not forcing you to memorize the shortcut keys while at the same time it gives you the possibility of learning these keys since every menu choice also lists the shortcut key, if one is available. In other words, you can use the menus as a sort of easily accessible help.

From the menus you enter the editing screen (where you actually create your screen) by hitting the <ESC>-key. If you have not changed the defaults in the SYSTEM and COLORS menu, an empty blue screen will appear, with a status line at the bottom.

To go back to the menu screen hit again the <ESC>-key. To abandon the screen generator program you must be in the menu screen and select the choice QUIT.

To draw something on a screen go into the edit screen. Move the cursor with the four arrow keys to somewhere in the middle of the screen and type a few characters. They will be written in the colors shown on the status line. If you make a small mistake, use the <BACKSPACE>-key or simply type over the mistake with the space bar.

To draw a box around your text or wherever you want, place the cursor where you want the left upper corner of the box to start and go to the menu screen by hitting the <ESC>-key. Choose the option LINES and select Box Empty. The edit screen will reappear, with the left upper corner marked. Move the cursor to where you want the right bottom corner of your box to be and hit <RETURN/ENTER>. Without effort you have your box. It is called an empty box because the inside does not get filled, that is, you can design the box around existing text.

While you were selecting the empty box from the menu you may have noticed that the shortcut key for the empty box is the <F5>-key. Try it out. Place the cursor where you want the left upper corner of your box to be and hit <F5>. Then, like before, move the cursor to where you want the box to end and hit <RETURN/ENTER> for an instant box.

In the same way that you draw a box, you can cut, copy or move parts of the screen. Whenever you cut or copy something, the results are put into the scratchpad, from where it can always be copied back in the original colors or in the selected colors by hitting the appropriate keys. Again don't try to memorize keys at the beginning, but use the menu.

To change the color of the text or lines you draw, go to the COLOR menu and make the appropriate selections. Of course you can also change the colors from the edit screen with the appropriate keystrokes.

The COLOR menu lets you also change the complete background of the screen. You should use this option when you start drawing a screen, and not after having done a lot of designing. Changing the background color of an existing design may not always produce the expected results, and you therefore should save your screen before choosing this option. That is the reason for the dire warning when selecting this option if you do not save the screen first.

Get acquainted with all the options of the SCREEN, LINES and CURSOR menus. See how you can change the color of an item by cutting or copying it and then redisplaying it in a different color.

The FILE menu lets you save, retrieve or cancel a screen.

Each screen is saved as a record in the file SCREENS.PFM. If you need more information on this file, please consult the entry Accessing the File SCREENS.PFM in the extended section of the screen generator online help.

By default the whole screen is saved, minus the status line, of course. You can also save a window, with or without color attributes. For further information on saving a window, consult the entry Saving a Window in the extended help.

The screen generator also lets you import text generated with a word processor from the operating system. Sections of the text can then be inserted where you want on the screen. For further information on saving a window, consult the entry Displaying Text in the extended help.

See also:

Online Help and Reference
Accessing the File SCREENS.PFM
Saving a Window
Displaying Text

Log File PRAGMA.LOG

View Topic

THE LOG FILE PRAGMA.LOG

Every time PRAGMA starts it enters the start time and date into a file called PRAGMA.LOG.

If an error is encountered while running an application, an entry is made into the log file, specifying where in the program the error was encountered and, if possible, the kind of error encountered.

When PRAGMA is terminated in an regular way this is entered into the log file to enable you to check back at any time to make sure termination was not done improperly, like by shutting off the computer or rebooting.

The PRAGMA log is very useful in helping you track down the causes of problems you may encounter when using PRAGMA programs.

The log file is named PRAGMA.LOG by default. Should you wish to change the name you can do so by editing the entry LOG FILE NAME in the Various Parameters section of the OPTIONS menu of the online help. If you want to disable the logging function, change the LOG FILE NAME entry to a blank.

If PRAGMA does not find the PRAGMA.LOG file, it is created. From then on, all entries will be appended to the file.

You should periodically check the size of the log file since it can become quite big, especially if you enter and leave PRAGMA often. When it is too big, delete the file so that a new file can be automatically started.

A entry for a PRAGMA session that was terminated in an orderly way will look like this:

************************************
1992 12 03 14 16 52
PRAGMA Started

PRAGMA Ended

The first line is the date and time that a particular PRAGMA session started.

If PRAGMA was not exited in an orderly way the line, PRAGMA Ended, will be missing.

Whenever a PRAGMA program does a system call, the lines System Call Started and System Call Ended are added to the log, because before doing a system call PRAGMA closes all its files. If a crash occurs while in a system call, you can still see that PRAGMA shut itself down in an orderly way.

If you interrupt the running of an application with <CONTROL-BREAK>, you will get an entry specifying the verb name and the line number where the interruption occurred. This entry into the log file will always be made, regardless whether the parameter ENTER DEBUGGER ON ERROR in the Various Parameters section of the OPTIONS menu of the online help is YES or NO.

If an error happens during the execution of a program, you will get an entry specifying the error, the verb name and the line number where the error occurred. Also this entry will always be made, regardless whether the debugger parameter ENTER DEBUGGER ON ERROR is YES or NO.

For example, an entry for a PRAGMA session in which the program has encountered an invalid numeric value will look like this:

************************************
1992 12 03 14 16 52
PRAGMA Started

Execution paused due to an invalid numeric noun value.
Noun name - TESTNOUN Current value - "Hello"
Verb name = TESTVERB
Line number - 10

Immediately after PRAGMA writes to the log file, the log file is closed and then reopened. This is to ascertain that the messages are actually written to the hard disk and not buffered somewhere in memory should the power fail or a manual reboot be done. Unfortunately the operating systems do not provide a totally reliable way to flush file data. If a disk cache program is installed, it may still keep disk write data in memory for some time, even if the log file was closed. This is a remote possibility, but nevertheless you cannot always be sure that everything was written to the hard disk.

See also:

Error Handling
Debugger

Message File PRMSG

View Topic

MESSAGE EDITOR

This sections lets you change or edit the PRAGMA message file, PRMSG.PFM.

The file PRMSG.PFM is the file that is used by PRAGMA, The PRAGMA SCREEN GENERATOR or other programs related to PRAGMA, for all the messages and screens. These messages or screens can be changed or translated to another language.

Menus are screen windows and are stored in PRMSG.PFM. Help messages are not stored in PRMSG.PFM but in PRAREF2.PFM.

To facilitate the editing or translation of the messages the program utilizes a help file, PRMSG2.PFM, that contains a name for each message, a short description and the date in which the message was last changed. PRMSG2.PFM also contains the original Logical message in English, as supplied by us and the modified or translated message.

Message editing is done on the PRMSG2.PFM file. Then, once you are satisfied that the translated message or messages are what you want, you can have the program copy the edited messages to the real PRMSG.PFM file.

Since the message editor also uses the PRMSG.PFM file for its own messages, you have the option to place your own PRMSG.PFM file into a separate directory and set a path to that directory for transferring messages to and from the PRMSG2.PFM file to your own PRMSG.PFM file. So you don't have to put the PRAGMA editor messages into your PRMSG.PFM file.

Other utilities also let you update the PRMSG2.PFM file from the PRMSG.PFM file.

PRMSG2.PFM contains the following information:

MESSAGE NUMBER
MESSAGE NAME
DATE OF LAST UPDATE
MESSAGE DESCRIPTION
ORIGINAL LOGICAL MESSAGE
NEW MESSAGE

MESSAGE NUMBER and MESSAGE NAME identify a message. The MESSAGE NUMBER corresponds to the message number in the PRMSG.PFM file. Message numbers lower than 30,000 are for text messages, while messages with a number higher than 30,000 are for screens or screen windows, usually generated with the PRAGMA screen generator program.

DATE OF LAST UPDATE is the date this particular message was last changed.

MESSAGE DESCRIPTION is a short description of the message.

ORIGINAL LOGICAL MESSAGE contains the English message or screen, as supplied by Logical, while NEW MESSAGE contains the message or screen edited by you. At any time you can copy either of these messages or screens to the PRMSG.PFM file. Screens are not directly displayed, but you must press the appropriate key to see them.

DISPLAY, EDIT OR DELETE A MESSAGE

Nr. is the message number. You should NEVER change it,
otherwise the program will copy a message or a screen
to the wrong place in PRMSG.PFM.

Logical is the original English message or screen, as supplied
Message by Logical. We recommend that you don't change it.
It is useful as a reference when translating.

New is where you enter or edit the new message or screen.
Message

To display, edit or delete a message, you first have to enter the number or the first letters of the name of the message that you want to see and edit. After having done so, the record chosen will be displayed. If you want to see a different record, you may proceed to the next one or the preceding one by hitting the up or down arrow keys.

Hitting the <F7> key lets you edit the record. The first field will be lighted and ready to be edited. To proceed to the next field hit <TAB>, to go back one field, hit <SHIFT-TAB>. <ESC> terminates the editing mode and saves the changed record. To abort hit <SHIFT-F10>.

When editing a message (message number smaller than 30,000) and the message field is highlighted, simply edit or enter a new message. To enter a control character, which is an underline in PRAGMA, use a caret (^). To enter an escape, which is a ^[ in PRAGMA, use a caret and an opening square bracket (^[).

For screens or screen windows (message number greater than 30,000) when you reach the message field you are given the option to enter the filename or the SCREENS.PFM record you want to import. SCREENS.PFM is a file that contains screens and windows generated with the PRAGMA screen generator program.

If you enter a filename, you can hit the <F2> key to import the file containing a screen from the operating system, or you can hit the <F3> key to export the contents of the message to an operating system file. These two options are only useful if you design a screen with a different program than the PRAGMA screen generator.

If you enter the number of a SCREENS.PFM record and hit the <F4> key, you import a screen or a screen window from the SCREENS.PFM file into the record.

The <F8> key lets you delete a record. You are given a last chance not to proceed before irreversibly deleting the displayed message. After deleting a record, the next record will be displayed.

The <F2> key lets you transfer the NEW message or screen to the message file PRMSG.PFM. If you have set a file path the message will be transferred to the PRMSG.PFM file in the directory indicated by the path.

The <F3> key lets you transfer the LOGICAL message or screen to the message file PRMSG.PFM, just in case you changed your mind and like our version better. Caution. The file path cannot be used with this option.

The <SHIFT-F3> key lets you transfer the current message or screen of the PRMSG.PFM file to the LOGICAL message. Caution. The file path cannot be used with this option.

The <F4> key lets you view the NEW message or screen on the screen, starting from row 2.

The <F5> key lets you view the ORIGINAL message or screen on the screen, starting from row 2.

The <F6> key lets you transfer the LOGICAL message to the NEW message field. This if you want to make only small changes to the message and don't feel like doing a lot of typing. Not very useful for screens.

CAUTION You can make your messages really fancy since you are allowed to enter ANSI control sequences in them. But always remember that many messages are used both for the screen and the printer, and a printer may not understand ANSI control sequences. Of course this warning does not apply for screens.

Also, not everybody's idea of art is a screen that looks like graffiti in the New York subway.

NEW MESSAGE

Lets you create a new message or screen. To abort hit <SHIFT-F10>.

This option should really not be used, unless you accidentally deleted a message. We don't recommend that you use the file PRMSG.PFM for your own programs, since at any time we may add more messages or screens to the file.

LIST ALL MESSAGES

Three choices are available.

The first choice is whether to display the listing on the screen or to make a printout. The second choice asks you where you want to begin the list and the third choice asks you where you want to end it. Default lists on the screen all the records in alphabetical order.

If you wish to access the records numerically, just enter the numbers indicating where you want the list to begin and end.

To proceed to the next choice use the <TAB> key.

When listing on the screen, one record will always be highlighted. By using the <UP> and <DOWN> arrow keys you can move the highlighting up and down. Hitting the <F9> key will display the record that is highlighted.

TRANSFER ALL LOGICAL TO PRMSG

Performs the same function as the <F3> key when editing a message, except that ALL the LOGICAL messages are transferred to the PRMSG.PFM file.

If you have set a file path all the messages will be transferred to the PRMSG.PFM file in the directory indicated by the path.

This feature is more useful for us than for you.

TRANSFER ALL NEW TO PRMSG

Performs the same function as the <F2> key when editing a message, except that ALL the NEW messages are transferred to the PRMSG.PFM file.

If you have set a file path all the messages will be transferred to the PRMSG.PFM file in the directory indicated by the path.

This feature is useful if you edit lots of messages at one sitting and then want to transfer them all at the same time.

TRANSFER ALL PRMSG TO LOGICAL

Transfers all the messages currently in the PRMSG.PFM file to the PRMSG2.PFM file, into the ORIGINAL LOGICAL MESSAGE field. You will not use this feature often, as it is mainly intended for our use, to make sure that the PRMSG2.PFM file is always current with the PRMSG.PFM file.

If a PRMSG.PFM message is not present in the PRMSG2.PFM file, a new record will be created in PRMSG2.PFM with the current date as the DATE OF LAST UPDATE. The MESSAGE NAME and MESSAGE DESCRIPTION will be blank, enabling you to quickly find these new records.

TRANSFER ALL PRMSG TO NEW

Transfers all the messages currently in the PRMSG.PFM file to the PRMSG2.PFM file, into the NEW MESSAGE field. This feature is useful if you have a translated PRMSG.PFM file and you receive a new PRMSG2.PFM file from us. Rather than doing a lot of retyping, use this utility to enter all your messages into the PRMSG2.PFM file.

If you have set a file path the message will be transferred from the PRMSG.PFM file in the directory indicated by the path.

If a PRMSG.PFM message is not present in the PRMSG2.PFM file, a new record will be created in PRMSG2.PFM with the current date as the DATE OF LAST UPDATE. The MESSAGE NAME and MESSAGE DESCRIPTION will be blank, enabling you to quickly find these new records.

CAREFUL! The menu choices that transfer these messages are very powerful and could yield results that you may not expect. So make sure that you always have a CURRENT backup of PRMSG.PFM and PRMSG2.PFM before using them.

Also make sure that you always keep the original PRMSG.PFM file in a SAFE place. If you get into trouble, before calling us, copy the original PRMSG.PFM file to your application directory and see what happens.

HINT: To find out the record number of a message, do the following. When entering the online help or another PRAGMA program and the program waits for any key to continue past the copyright screen, enter a "D" (capital D) When displaying most messages or screens, the record number is also displayed.

SET PRMSG.PFM PATH

Lets you set a path to a directory where you put your own PRMSG.PFM file.

This enables you to have a PRMSG.PFM file that does not contain the messages of the PRAGMA editor.

This path works only for transferring the NEW messages to a PRMSG.PFM file.

RECORD #999 contains information on when the file was last updated. This information is used by the PRAGMA online help in the PRAGMA system option.

ACCESSING THE FILES

The following section describes how to access the PRAGMA message files from PRAGMA. Be sure not to exceed some critical noun lengths!

To access the PRAGMA editor files you must have a PFM NUMERIC REFS = YES statement in your description file.

This is the file definition of PRMSG.PFM.

RECAP the definition of PRMSG

The short name is PRMSG
The Btrieve open mode is 0
The PFM unit size is 96
The mock flag is 16
The number of indexes is 1
The significant length of index 1 is 8

1 MSG KEY NO (index selection noun)
2 MSG ID (reference, numeric)
3 MSG TEXT

Make sure that MSG TXT never exceeds 500 bytes in length, when used for PRAGMA.EXE messages. (Message numbers below 1000.) Control characters count as two!

This is the file definition of PRMSG2.PFM.

RECAP the definition of PRMSG2

The short name is PRMSG2
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 16
The number of indexes is 3
The significant length of index 1 is 8
The significant length of index 2 is 50
The significant length of index 3 is 18

1 ED MSG KEY (index selection noun)
2 ED MSG NR (reference 1, unique, numeric)
3 ED MSG NAME REF (reference 2, obtained by
joining ED MSG NAME, padded to
40, in front of ED MSG NR)
4 ED MSG LAST UPDATE REF (reference 3, obtained by joining
ED MSG LAST UPDATE, 6 characters,
in front of ED MSG NR)
5 ED MSG NAME
6 ED MSG LAST UPDATE
7 ED MSG DESCRIPTION
8 ED MSG LBS
9 ED MSG OTHER

Names and Numbers in PRAGMA

View Topic

NAMES AND NUMBERS IN PRAGMA

NOUN NAMES

A valid noun name may consist of no more than 31 characters, and may be entirely alphabetic, or a combination of letters, numbers and spaces. Leading, trailing and multiple contiguous spaces are not allowed.

A number by itself may not be used as a noun name.

Special characters such as hyphens and percent signs may be incorporated into a noun name. Special characters may also stand alone as a noun name. Exceptions are the quotation ("), minus sign (-), plus sign (+), asterisk (*), diagonal (/), greater than sign (>), less than sign (<), equal to sign (=), and the caret (^), all of which have special uses in PRAGMA and may not be used as stand alone noun names.

Valid noun names Invalid noun names

TOTAL PAY TO DATE 124
HOLD #3 "Name"
% *
SOC-SEC-NUM ZIP CODE

FILE NAMES

File names follow the same rules, with the exception that you must be careful when choosing the first eight characters of the filename. This is because PRAGMA has to take the file name (longname) and convert it to a short file name (shortname) in order to accommodate the DOS file name restriction of maximum 8 characters before the extension. In the shortname PRAGMA also substitutes all the nonalphanumeric characters with underlines. In other words, the only characters allowed in the shortname are letters from A to Z and the digits from 0 to 9 and the underline. This is done to avoid any possible conflicts with the operating systems and to be compatible with the C language. You can immediately see the shortname created by PRAGMA in the header of a file definition.

The shortname is also the name that has to be used with FILEUTIL or BUTIL to create an empty file in the operating system. So be careful when creating a PRAGMA file name and make sure that the resulting shortname is not a duplicate of an already existing shortname. You may edit the shortname of a file without having to change the longname. But remember that the corresponding file in the operating system must be named the same name with the added extension PFM or BTR.

VALID VERB NAMES

A valid verb name may consist of no more than 31 characters, and may be entirely alphabetic, or a combination of letters, numbers and spaces. Leading, trailing and multiple contiguous spaces are not allowed.

Special characters such as hyphens and percent signs may be incorporated into a verb name. Special characters may also stand alone as a verb name. Exceptions are the quotation ("), minus sign (-), plus sign (+), asterisk (*), diagonal (/), greater than sign (>), less than sign (<), equal to sign (=), and the caret (^), all of which have special uses in PRAGMA and may not be used as stand alone verb names.

A number by itself may not be used as a verb name.

VALID NUMBERS

A valid number may contain up to 14 digits, excluding optional leading signs ( + or - ), decimal points, $ signs, and correctly positioned commas.

If commas are incorrectly positioned during INPUT from the keyboard, PRAGMA accepts the invalid numeric entry as an expression. See the standard verb IF for methods of checking invalid numeric entries.

Examples of valid numbers:

.01 -40
1 +100
12.3456 $12,345
1234 -12,345.12345678
1,234 -$10.05 (minus sign followed by $ sign)

Examples of invalid numbers:

1234,56,000 (commas incorrectly positioned)
12345678901234567 (more than 14 digits)
$-123.45 ($ sign followed by minus sign)

NUMBER RANGE

The 14 digit maximum provides a range that should suit all business applications. In normal use the following numbers are the largest and smallest possible:

+ or - 99,999,999,999,999
+ or - 0.0000000000001

In special calculations, however, a greater range is possible. Internally, PRAGMA is capable of handling numbers within a range whose limits are greater than + 10-33 to + 10+94. It is unlikely that you would use numbers of this size.

If you instruct PRAGMA to display or print a number of more than 14 significant digits, the number will not appear; instead a string of asterisks (*****************) will appear. This can be avoided by moving the decimal point a sufficient number of places to the left prior to outputting the number. Divide the too large number by 10, 100, 1000 or so on, or multiply it by .01, or .001, and so on.

NAMING PRECEDENCE

PRAGMA lets you name a verb, noun or file with the name or the abbreviation of a standard word. This is not an error or oversight. It is simply impossible to totally prevent you from doing so.

Standards may be deleted from PRSTD.PFM, the file that contains all the standard words. New standards may be added at a later time. And what about different languages? What if you take an application into another language by using a different PRSTD.PFM? What if there is then a conflict between a user word and a standard word?

All of these things can and will happen, and there is nothing that can be done to maintain a foolproof distinction between user names and standard names. There is always the possibility that you can get into a situation of having the same name being used for two things.

Even if a standard and a user word turn out to have the same name, no matter how it got to be that way, you can always RENAME the user word.

User words are searched BEFORE the standards. In other words, PRAGMA searches the PRVOCAB file before the PRSTD file. RENAME does not search the standards at all. There is no need to, because you cannot rename a standard word by using RENAME. You must use the standards editor for that.

So, if you accidentally name a verb like a standard or a standard abbreviation, simply RENAME it and the next time that you do a SELECTIVE SAVE to clean out your vocab of unused stuff, it will be automatically eliminated.

ONLINE HELP 1200 - 1999

View Topic

Object Verbs

View Topic

OBJECT VERBS

CHANGING THE NUMBER OF PARAMETERS

It is possible to crash the system if you use object verbs with the incorrect number of parameters. For instance, you create an object verb and you decide it needs two parameters. You then use that object verb in a number of other verbs and, of course, you must give two parameters in each usage.

Later, you alter the object verb and make it use three parameters. The other verbs where this object verb is used all still have two parameters given, and they do not know that you have changed the object verb to require three parameters. When you try to run these verbs, the system will crash.

This same problem also exists in PRAGMA 3. But in that case, only one object is ever needed, and if it is missing, to prevent a crash from occurring, the standard noun OBJECT is substituted.

The definition editor disallows the lowering of the object count if those objects are still used in the verb itself.

Whenever you attempt to set the object count lower than it presently is, PRAGMA immediately searches through the entire verb definition for usage of any of the objects you are attempting to delete. If any of them are still used, PRAGMA ignores your attempt to lower the object count, and positions you to the first such usage.

This is similar to the way that missing labels are handled.

You may only lower the object count when the objects you are removing are not used anywhere within the verb.

This disallowing of lowering the number of objects only eliminates the possibility of using deleted objects within the object verb itself. It does not help you if you have used this object verb in another verb.

If you change the object count of an object verb, and if this object verb is used in any other verb, the using verb now will have an incorrect number of objects in the definition line where it uses the object verb. This can crash the system.

If you change the number of objects in an object verb, you must IMMEDIATELY go to every verb that uses it and reenter those definition lines. The definition editor will then reparse those lines. You will have to enter any extra objects that may be needed, or any objects not needed will be automatically discarded.

CONVERTING FROM PRAGMA 3

When translating an application from PRAGMA 3, PRA2PFM translates the object name to OB1, to avoid confusion with the standard word OBJECT, leaving the prompt of "object is".

There is only one object possible in PRAGMA 3, and so there is no real need to use specific prompts or names, and to ask for them during conversion would be pointless. So PRA2PFM simply gives them the prompt that you are used to. You can of course edit them after converting.

There is still a standard noun called OBJECT in PRAGMA 4. But it no longer has any special meaning. It is a noun like any other noun. And you usually will never use it. A program converted from PRAGMA 3 with PRA2PFM, with the object name of OB1 never uses the standard noun OBJECT.

The name OB1 in this case is the local object name. This avoids a possible confusion of having two things called OBJECT, since they are both very different. The object OB1 refers to some noun, the standard noun OBJECT refers always to the standard noun OBJECT. And the standard noun OBJECT also still has the abbreviation of OB. BUT PRAGMA 4 objects DO NOT HAVE ABBREVIATIONS.

If you translated with an early version of PRA2PFM the object name was translated to OBJECT, opening the possibility of confusion. If in doubt simply change the name of the object in the header of the verb from OBJECT to something more meaningful. You will immediately notice in the verb itself if there has been a mixup between the object name OBJECT and the standard noun OBJECT.

Online Help and Reference

View Topic

Operating Modes of PRAGMA

View Topic

PRAGMA OPERATING MODES

PRAGMA SOFTWARE DEVELOPMENT SYSTEM

The PRAGMA software development system is started by simply typing PRAGMA. At the START message you type the name of the verb that you want to run, or if present, the verb AUTOEXEC. Be aware that PRAGMA is case sensitive, unless you restrict it to upper case only by setting the LOWER TO UPPER CASE statement to YES in the options menu of the online help. When the program has terminated you will be back at the START message. To go back to the operating system simply hit <RETURN/ENTER> at the START message.

You may also start PRAGMA by typing on the command line after PRAGMA the name of the verb that you wish to run. Every single command line item is terminated inside PRAGMA with a return key, so if you you want to include spaces, you must bound them with double quotes (") so that PRAGMA sees them as one item. To include a double quote character inside of a command line item, you must precede it by a backslash (\). To send a lone return key, type a null string ("").

To operate, PRAGMA must have at least the following files present:

PRVOCAB.PFM
Whatever .PFM or .BTR files you need
PRMSG.PFM
PRSTD.PFM
PRAGMA.DES
TERMINFO.LBS

The online help files need not be present, but in that case most of the online help will not be accessible.

Under DOS, if you are using Btrieve files, you must load Btrieve before starting PRAGMA.

When PRAGMA.EXE starts, it looks for PRAGMA.DES, the description file that contains all the parameters for the program. If it cannot find it, it will use defaults. But using defaults will more than likely produce unexpected results.

When running PRAGMA, the online help (type <F1> at the START message) is always accessible.

To be able to run the PRAGMA development system under DOS or OS/2 you must have a DOS Programmable or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort or enter demo mode. Any SCO UNIX Programmable or hierarchically higher security device will also work for DOS or OS/2.

To be able to run the PRAGMA development system under SCO UNIX you must have an SCO UNIX Programmable or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort. DOS parallel security devices will not work for UNIX.

RUNTIME PRAGMA

The runtime version of PRAGMA is started by typing "PRAGMA" on the operating system command line, followed by the name of the startup verb. If the security device plugged into your parallel printer port is either a DOS - OS/2 Runtime or a SCO UNIX Runtime device, PRAGMA will automatically default to the runtime version.

Once the runtime version is started it will run the verb entered on the command line. When the execution of all the verbs is finished the runtime version of PRAGMA will go back to the operating system prompt.

If no verb name was entered on the command line, it will try to run the PRAGMA verb AUTOEXEC. Do not confuse this verb with the AUTOEXEC.BAT file in your DOS root directory. It has nothing to do with that.

To operate the runtime version of PRAGMA you must have the same files present as for the PRAGMA Software Development System:

PRVOCAB.PFM
Whatever .PFM or .BTR files you need
PRMSG.PFM
PRSTD.PFM
PRAGMA.DES
TERMINFO.LBS

Under DOS, if you are using Btrieve files, you must load Btrieve before starting PRAGMA.

When the runtime version of PRAGMA starts, it looks for PRAGMA.DES, the description file that contains all the parameters for the program. If it cannot find it, it will use defaults. But using defaults will more than likely produce unexpected results.

To be able to run the runtime version of PRAGMA under DOS or OS/2 you must have a DOS Runtime or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort. Any SCO UNIX Runtime or hierarchically higher security device will also work for DOS or OS/2.

To be able to run the runtime version of PRAGMA under SCO UNIX you must have an SCO UNIX Runtime or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort or enter demo mode. DOS parallel security devices will not work for UNIX.

COMPILED PRAGMA PROGRAM

A PRAGMA application can be translated to C sourcecode and then compiled to the various operating systems to become a stand-alone executable file. The advantages of compiled code over interpreted code are mainly execution speed and the fact that nobody can alter your program.

No knowledge of the C language is required to compile a PRAGMA application. We provide you with all the necessary instructions to translate and then compile an application.

A compiled PRAGMA application is started by simply typing its name at the operating system prompt. It will then behave like an application running with the runtime version of the interpreter. The verb AUTOEXEC is the starting verb, and when the execution of all the verbs is finished the program will go back to the operating system prompt.

To run a compiled PRAGMA program (YOURNAME.EXE) the following files must also be present:

Whatever .PFM or .BTR files you need
PRAGMA.DES or YOURNAME.DES
TERMINFO.LBS

Under DOS, if you are using Btrieve files, you must load Btrieve before starting the compiled PRAGMA program.

When YOURNAME.EXE starts, it looks for YOURNAME.DES, the description file that contains all the parameters for the program. If it cannot find YOURNAME.DES it will look for PRAGMA.DES, and failing that, it will use defaults. But using defaults will more than likely produce unexpected results.

The operating system environment must be set as it is for interpreted PRAGMA, described at the beginning of this section.

To be able to run a compiled PRAGMA program under DOS or OS/2 you must have a Runtime or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort or enter demo mode. Any SCO UNIX Runtime or hierarchically higher security device will also work for DOS or OS/2.

To be able to run a compiled PRAGMA program under SCO UNIX you must have an SCO UNIX Runtime or hierarchically higher security device plugged into your parallel printer port. If you don't have such a device, the program will abort or enter demo mode. DOS parallel security devices will not work for UNIX.

PRAGMA DEMO MODE

If you start PRAGMA without a security device, PRAGMA will abort or will run in one of the two demo modes, depending on the parameter DEMO MODE in the description file PRAGMA.DES.

When PRAGMA.DES has the statement DEMO MODE = DISABLED or no demo mode statement, PRAGMA will not start but display a security error message instead.

When PRAGMA.DES has the statement DEMO MODE = APPLICATION, PRAGMA will allow any size application to be demonstrated, but the system will bail out to the operating system after a certain amount of activity with a security error. You cannot modify, add or delete anything permanently to the vocabulary since any writing to the vocabulary is discarded.

When PRAGMA.DES has the statement DEMO MODE = LANGUAGE, PRAGMA allows the language and a small program to be demonstrated. The system will only start and run if the vocabulary is under a certain size. Within the vocabulary size limit everything is permitted.

In both demo modes the online help (type <F1> at the START message) is always accessible.

Operating Systems Overview

View Topic

OPERATING SYSTEMS OVERVIEW

PRAGMA is a language that produces portable applications. You can take your application and run it with no changes, or only minimal ones, under MS-DOS, OS/2, SCO UNIX or other UNIX dialects.

Every operating system has its advantages and disadvantages, and PRAGMA is naturally subject to the limitations of each operating system while reflecting its features.

DOS

Under the DOS operating system a PRAGMA program is strictly single task and single user. If the same program and data must be shared by multiple users, it is necessary to run PRAGMA from a network.

The DOS version of PRAGMA has been written for 386 machines, or better. A DOS extender will use all the available extended memory available on the machine and then if necessary swap memory to disk. To take full advantage of the extender your RAM memory should be accessed by a 32 bit wide path. PRAGMA can use a mathematical coprocessor, if one is available. A mathematical coprocessor will greatly enhance the speed of PRAGMA on any machine, regardless of operating system.

This version will also run inder Microsoft Windows.

PRAGMA's Fileserver cannot be used with this version of PRAGMA, due to the way the extender operates.

For DOS we suggest that you use Microsoft version 5.0 or higher. Earlier versions may work, albeit at slower speeds, but they must be version 3.3 or higher.

OS/2

Under OS/2 the operating system will automatically take care of memory management. Also, since OS/2 is multitasking, you are able to run multiple versions of your program on the same machine.

OS/2 is not a multiuser operating system, and to make it multiuser you will have to install a network.

You can install both DOS and OS/2 in the same partition if you use the FAT file system for OS/2 and switch from one operating system to the other with a utility supplied by IBM called Multiboot. Since OS/2 uses the same file system as DOS, all your PFM or Btrieve files can be directly accessed by OS/2, making the transition very simple.

The new OS/2 file system, called HPFS, is also supported by PRAGMA. In fact, to PRAGMA there is no difference at all. HPFS has more capabilities than the older file system (called FAT), but these are not currently required by PRAGMA. So your program will operate just fine using HPFS, in as much as any DOS program can use HPFS under OS/2 without knowing about it. You may also have an extended DOS partition (FAT) and HPFS partition on the same machine, making the file transfer form DOS to OS/2 very easy.

To take full advantage of your OS/2 system your RAM memory should be accessed by a 32 bit wide path.

PRAGMA can use a mathematical coprocessor, if one is available. A mathematical coprocessor will greatly enhance the speed of PRAGMA on any machine, regardless of operating system.

For OS/2 you must use IBM version 2.0 or higher.

SCO UNIX

UNIX has no memory limitations and here PRAGMA becomes both multitasking and multiuser. The number of users is determined by the hardware.

There are more than one hundred dialects of UNIX in the world. While they all share similarities, there are enough differences between them to exclude the possibility of one PRAGMA UNIX version from running on all the different versions of UNIX. So much for standardization.

Under SCO UNIX we mean both versions currently sold by Santa Cruz Operations: UNIX version 3.2 and the earlier Xenix 386 version 2.3.2. The PRAGMA for SCO UNIX works for both versions of UNIX. Interactive UNIX is compatible with SCO UNIX and PRAGMA for SCO UNIX will also work on it.

To run interpreted PRAGMA or a compiled PRAGMA application under SCO UNIX you only need the operating system. The complete SCO development package is only necessary if you plan to compile PRAGMA applications.

SCO also supplies a limited version of UNIX, at a reduced price, that is especially suited if you only need a user or two and is the ideal replacement of a PRAGMA 3 multiuser system.

Be aware that SCO UNIX 386 is a true 386 operating system. You therefore must use a 386 computer and to get the maximum speed out of your system your RAM memory should be accessed by a 32 bit wide path.

PRAGMA can use a mathematical coprocessor, if one is available. A mathematical coprocessor will greatly enhance the speed of PRAGMA on any machine, regardless of operating system.

OTHER UNIX DIALECTS

We are planning to support PRAGMA on other versions of UNIX and non-INTEL computers. If you have a particular machine in mind, let us know and we will discuss this option with you.

PRAGMA 4 can run on almost any UNIX system that is derived from the AT&T UNIX SVR3 or SVR4 (System V, release 3 or 4). PRAGMA 4 will also probably work on non AT&T UNIX, like Berkley UNIX. Since there are over 100 different UNIX dialects, it is impossible for us to have an updated version of PRAGMA for every one of them. To install PRAGMA 4 for the first time on one of these UNIX systems you must give us access to your machine with a modem. In detail this is what you need to provide us:

The UNIX system with the full development system.

Please have all the UNIX manual pages installed and
available.

The modem must support a 9600 baud rate and the V 32
and V 42 protocol. A Telebit modem is preferred but
not necessary. All modem connections and log-ins must
be vertified by you before we begin. We need the
ability to log-in multiple times.

The UNIX system must have the Kermit program. It is
needed to transfer PRAGMA to the new system. It is a
common program and should not be a problem to obtain.

The UNIX system should have the utility "compress".
This is a public domain UNIX utility like PKZIP.
We can do without it, but it is nice to have.

A user account has to be set up on the system, and we
need to know its log on name and password. This
account does not need any special privileges, but must
have read/write/execute permission in the directory
where libraries are stored (probably /usr/lib) so that
we can put files in there for linking.

Read write permission must be given to everybody for
the port where the security device resides.

We need the name and phone number of a person who knows
the C language and who knows thoroughly the operating
system we will be compiling on. That person must have
been informed that we might call and he must speak
English.

But we would like to make a suggestion to spare both you and us a lot of grief. Unless you already are a UNIX guru, get your first UNIX experience on an INTEL type of computer running either of the two SCO UNIX versions. Once you are familiar with this UNIX and have run one of your applications under it, we will port you over to the new system.

NETWORKS

Although networks are not operating systems in the strictest sense, they are different enough from a stand alone machine to warrant special mention.

All three operating systems supported by PRAGMA have networks, and a PRAGMA application can be networked on any of them.

When networking a PRAGMA application we suggest that you put the data files on the network server and install PRAGMA at each workstation, especially if you are using the WRITE NOUNS = YES option, where you must keep a separate vocab for each user or if you must do a lot of memory swapping.

But you can also install PRAGMA and all the data files on the server. This lets you use diskless workstations, provided that they are equipped with enough memory.

See also:

Environment Configuration - DOS
Environment Configuration - OS/2
Environment Configuration - UNIX

P4TERM and UNIX

View Topic

P4TERM AND UNIX

For the UNIX system to be able to communicate with P4TERM through a serial port and a null modem cable you first must be sure that the serial port on the UNIX system has been enabled. The online help entry UNIX - Terminals will assist you in doing so. But make sure that P4TERM is up and running correctly as explained in the online help entry Running P4TERM.

Once you are at the login prompt and have entered the UNIX system you must make sure that the UNIX system knows that a P4TERM type of terminal is attached to that particular serial port. P4TERM is custom tailored to PRAGMA (it understands commands from PRAGMA to create a window, raise it, select it, etc.) and therefore cannot exploit its full power if you use the standard UNIX terminal description "ansi". Instead, use the terminal description "p4term" or "p4termmono" to access all the features that PRAGMA supports.

Do not confuse the terminal description that P4TERM requires on DOS for itself (P4TERMMEM or P4TERMANSI) and the terminal description that the UNIX system uses to communicate with P4TERM (p4term). These are all contained in TERMINFO.LBS but are used by different programs.

To see what TERM is active, type the following command at the UNIX prompt:

env

env stands for environment. To change TERM, you enter, always from the terminal that is running P4TERM, the following line:

TERM=p4term; export TERM

Another, more permanent way of setting the TERM environment variable is by editing the file .profile in the user's home directory.

Go to the directory where you have all the PRAGMA files and start PRAGMA. When you are at the familiar START prompt, enter the online help and spend a few minutes accessing the various menus. Especially exercise the function and arrow keys. If everything acts normal, you are in business.

If you find that you exit a menu or even the online help for no reason, you must change the parameter KEYBOARD LOOP COUNT in PRAGMA.DES. The default is 100. Temporarily set it to 200. To change the parameter you can go to the online help, Options menu, Various Parameters. You may have to space each keystroke by a few seconds to get there. Or use your favorite editor and directly make the change to PRAGMA.DES. If the problem persists, you may have to even go higher than 200 with the KEYBOARD LOOP COUNT parameter.

So far so good. You are now in business running PRAGMA. Unfortunately you have now set the TERM environmental variable to a value other UNIX programs like VI don't understand and therefore cannot function. To get out of this problem the P4TERM release diskette contains two textfiles called P4TERM.TI and P4TERM.TC. They are terminal descriptions for terminfo.src and termcap. Use your favorite text editor and integrate the description contained in P4TERM.TI into terminfo.src and P4TERM.TC into termcap. After editing terminfo.src you must recompile it using tic. For more information, consult your UNIX manuals.

See Also:

P4TERM - Running
UNIX - Terminals

P4TERM - Installation

View Topic

P4TERM INSTALLATION

The P4TERM program works only under DOS. Being a close relative of PRAGMA's (a lot of the PRAGMA 4 code found in PRAGMA.LIB has been used), before you install it you must first make the same additions or changes to the operating system that you would do for PRAGMA itself.

SHARE.EXE must be installed and the environment variable TERM must be set to P4TERMMEM or P4TERMANSI. Usually P4TERMMEM should be used because it is memory mapped and very fast. For more information on configuring DOS for P4TERM please consult the Environment Configuration section of the PRAGMA 4 Getting Started manual.

The P4TERM diskette contains all the necessary files to run the terminal emulator program and its online help. The .PFM files are the same ones used by PRAGMA, and they may be used either for P4TERM or PRAGMA. But be careful and only use up-to-date files.

On your hard disk make a subdirectory called, for instance, P4TERM. Then copy the executable file from the P4TERM diskette to this newly created subdirectory.

To save space the P4TERM files have been compressed. To extract them simply type the name of the executable file in the subdirectory. After the self-extraction process the directory will contain the following files:

P4TERM.EXE
P4TERM.DES
PRMSG.PFM
PRAREF2.PFM (used only by the online help)
PRADES.PFM (used only by the online help)
PRAPRINT.PFM (used only by the online help)
TERMINFO.LBS
COMIO.COM
P4TERM.TC
P4TERM.TI

P4TERM.EXE
The terminal emulator program.

P4TERM.DES
The text file that contains various parameters which are user definable.

PRMSG.PFM
The file that contains all the messages of P4TERM, PRAGMA and PREDIT.

PRAREF2.PFM
The help file that contains all the help texts like the one you are reading now for P4TERM and PRAGMA.

PRADES.PFM
The help file that contains descriptions of all the parameters of P4TERM.DES and PRAGMA.DES for the online help.

PRAPRINT.PFM
The file that contains the print parameters for various printers. It is used by the online help of P4TERM and PRAGMA.

TERMINFO.LBS
A text file that describes the characteristics of the terminal. It is expected to be in the directory where P4TERM or PRAGMA are or you can put it into a subdirectory called \USR\LIB\TERMINFO.

COMIO.COM
Interrupt driven communication handler. This same COMIO program is used by P4TERM and PRAGMA.

P4TERM.TI
The P4TERM terminal description file for terminfo.src on the UNIX machine.

P4TERM.TC
The P4TERM terminal description file for termcap on the UNIX machine.

The files PRAREF2.PFM, PRADES.PFM and PRAPRINT.PFM are only used by the online help and can be omitted, if necessary.

P4TERM.TI and P4TERM.TC are text files that can be integrated into the main files of your UNIX system using your favorite text exitor. After editing terminfo.src, it must be recompiled using the utility tic. For more information please consult the entry UNIX - Terminals and your UNIX manual.

See Also:

P4TERM - Introduction
COMIO Communication Handler for DOS
P4TERM - Running
P4TERM - Options
P4TERM and UNIX
UNIX - Terminals

P4TERM - Introduction

View Topic

P4TERM - Options

View Topic

P4TERM OPTIONS

P4TERM.DES is text file containing the user definable parameters for the terminal emulator program.

It follows the same syntax rules as the text file PRAGMA.DES.

If no P4TERM.DES description file is present when you start P4TERM, the program will look for PRAGMA.DES. If no PRAGMA.DES file is present, the default values will be used. But be careful. P4TERM is useless when using default values since no serial communication port will be chosen.

The Options menu of the P4TERM online help edits the P4TERM.DES file. This is the easiest way to make changes in it. If you use the online help to edit the P4TERM.DES file, default values are never written to the file, and if a default value is chosen, the corresponding line will be deleted.

You can also use any text editor to directly edit the P4TERM.DES file, taking care to use the proper syntax. Each of the parameter strings must be followed by a space, an equal sign, and another space before the value is specified. Any string therein is insensitive to case, except for the file status messages. For example:

PRINTER = LPT1

Control characters are preceded by an underline, like ^M. No quotes. But take note that when using the online help, control characters are written with a caret (^), like this ^M.

P4TERM PARAMETERS

The following parameters are the most important ones used by P4TERM:

COMMUNICATIONS =
PRINTER =

P4TERM EXIT KEY =
P4TERM SHELL KEY =
P4TERM HEX MODE KEY =

The syntax is the same as when using these or other similar parameters for PRAGMA.DES.

Be aware, that if you want to change the default settings for the keys, the key values you must use may differ from the standard PRAGMA key values. Please consult the P4TERM online help by selecting the Options menu, P4TERM Key Options.

To access the P4TERM online help, hit the <F1> key.

The online help of P4TERM, Options menu, explains all the available parameters and lets you change them, excepting the COMMUNICATIONS and PRINTER parameters which are changed in the Setup menu of the online help.

See Also:

P4TERM - Installation
P4TERM - Running
P4TERM and UNIX

P4TERM - Running

View Topic

RUNNING P4TERM

If your DOS environment has been set up correctly and all the necessary files are present, the last item to check is whether you have the correct parameters in the P4TERM.DES file.

P4TERM.DES is the equivalent of PRAGMA.DES for P4TERM. P4TERM reads P4TERM.DES to find its configuration parameters. It uses the serial port specified by COMMUNICATIONS = as the main I/O port for screen and keyboard data. It uses the port or file specified by PRINTER = as the destination for printed data. If P4TERM.DES is not found, an attempt is made to read PRAGMA.DES. If PRAGMA.DES is also absent, P4TERM will use defaults. But since the default for COMMUNICATIONS is no serial port, this option makes P4TERM practically useless.

If for instance, your null modem cable is attached to COM1, make sure that you have the entry

COMMUNICATIONS = COM1

in P4TERM.DES.

Next start the communication handler COMIO. Since you should always communicate with a UNIX system using the Xon/Xoff protocol, start COMIO with the following command:

COMIO /X

The communications parameters on DOS can also be set with COMIO. The default settings for most UNIX systems to communicate with the terminals are 9600 baud, no parity, 8 data bits and 1 stop bit. The following command accomplishes this, for COM1:

COMIO /COM1:96,N,8,1

Please refer to the help entry COMIO Communication Handler for DOS for further details.

No security device is needed to run P4TERM. To start it type P4TERM.

After displaying the copyright messages the blinking cursor will indicate that P4TERM is ready to start receiving and transmitting data. To establish communication with the UNIX system hit the <RETURN/ENTER> key a few times and if everything has been correctly set on the UNIX system, you will immediately see the familiar logon prompt.

To exit P4TERM, the default key is <ALT-F10>. It causes P4TERM to stop and then it closes all open files and cleans up after itself. But be aware that COMIO will still be active unless you tell it to disable the driver or reboot the machine.

To momentarily suspend what you are working on in P4TERM and go momentarily to another DOS program, the default key is <ALT-F6>. You will then shell to DOS, and can there do anything you wish while P4TERM maintains all of its memory, allowing you to go back to exactly the same screen you left. To reenter P4TERM after having shelled out, simply type EXIT at the DOS prompt.

Do not simply exit P4TERM in the middle of a PRAGMA program because doing so may cause PRAGMA running on the UNIX system and P4TERM to get out of sync. Shell out to DOS instead.

To toggle to hex dump mode, the default key is <ALT-F2>. The hex mode is used primarily for debugging. When in hex mode, P4TERM displays each byte of data received as a two digit hexadecimal number instead of just displaying it.

To override the default settings for these keys, use the following strings in P4TERM.DES:

P4TERM EXIT KEY =
P4TERM SHELL KEY =
P4TERM HEX MODE KEY =

Be aware, that if you want to change the default settings for the keys, the key values you must use may differ from the standard PRAGMA key values. Please consult the P4TERM online help by selecting the Options menu, P4TERM Key Options.

To access the P4TERM online help, hit the <F1> key. From the P4TERM online help you can also access the PRAGMA online help by selecting the appropriate entry in the Help menu. The online help also lets you change communication settings.

For further information on how to run P4TERM with the UNIX system, please consult the P4TERM and UNIX entry.

See Also:

P4TERM - Installation
COMIO Communication Handler for DOS
P4TERM - Options
P4TERM and UNIX
UNIX - Terminals

View Topic

PRAGMA TUTORIAL 7000 - 7999

View Topic

Printer File PRAPRINT.PFM

View Topic

THE PRINTER FILE PRAPRINT

The file PRAPRINT.PFM is used by the on-line help whenever you want to print a reference or a help text.

Which record of PRAPRINT.PFM is used is determined by the parameter FILE RECORD NAME FOR PRINTING in the PRAGMA description file. The contents of the selected PRAPRINT.PFM record can be seen from the FILE RECORD NAME FOR PRINTING option of the online help.

If the file is not present or the parameter is not correctly chosen, default values will be used.

The PRAPRINT.PFM file can be edited and viewed in the utilities section of the online help.

The file PRAPRINT.PFM contains the following information:

PRINTER NUMBER
PRINTER NAME
PRINTER DESCRIPTION
PRINT RESET
PRINT INDENT
PRINT FORM FEED
PRINT NORMAL
Print normal comment
PRINT COMPRESSED
PRINT COMPRESSED OFF
Print compressed comment
PRINT BOLD
PRINT BOLD OFF
Print bold comment
PRINT EXPANDED
PRINT EXPANDED OFF
Print expanded comment
PRINT ITALICS
PRINT ITALICS OFF
Print italics comment

PRINTER NUMBER and PRINTER NAME identify a printer record.

PRINTER DESCRIPTION allows for a short description, particularly useful for laser printers with their large font choices.

PRINT RESET contains the control characters to reset a printer. Mostly used for laser printers.

PRINT INDENT is a field where you input as many spaces as you need, to create an indentation or a margin that stays the same length, regardless of which font or printer you are using.

FORM FEED contains the necessary control characters that eject a page. The form feed character is supposed to be the same for all printers, but who knows what may happen in the future.

PRINT NORMAL, PRINT BOLD, etc. have names that today may not always be meaningful. Maybe we should rename them PRINT #1, PRINT #2, etc., because in reality you can put into these fields any printer information you want. So you are not at all as constrained as it may seem at first glance.

To accommodate those printers where each control character that turns ON a mode has an equivalent control character to turn the mode OFF we have followed the same procedure. A PRINT BOLD, for instance, is coupled with PRINT BOLD OFF and so on. This is not necessary for laser printers because with laser printers you just change a font, you don't turn it off. In this case the OFF fields must contain the same control sequence as PRINT NORMAL.

Since it is easy to get confused with so many different ways of printing, every printing mode has also a field for a comment.

You can have as many initialization records as you wish, therefore giving you practically an unlimited number of printers or fonts.

LASER PRINTER MANAGEMENT

To change a font in a laser printer you simply send to it the control sequence of the new font. There is no need to turn a chosen font "OFF". But to stay compatible with older printers that require that you turn a font off, each "ON" field has its corresponding "OFF" field.

So, for laser printers, choose a font such as PRINT NORMAL and the fonts that will best suit you for PRINT BOLD, PRINT CONDENSED, etc. For PRINT BOLD OFF and PRINT CONDENSED OFF insert the values of PRINT NORMAL.

PRAPRINT.PFM DEFINITION

RECAP the definition of PRAPRINT

The short name is PRAPRINT
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 16
The number of indexes is 2
The significant length of index 1 is 8
The significant length of index 2 is 32

1 PRN KEY (index selection noun)
2 PRN NR (reference, numeric, no duplicates)
3 PRN NAME REF (reference 2, obtained by joining
SY PRN NAME, padded to 24, in front
of SY PRN NR)
4 PRN NAME
5 PRN COMMENT
6 PRINT NORMAL
7 PRINT NORMAL COMMENT
8 PRINT INDENT
9 PRINT FORM FEED
10 PRINT COMPRESSED
11 PRINT COMPRESSED OFF
12 PRINT COMPRESSED COMMENT
13 PRINT BOLD
14 PRINT BOLD OFF
15 PRINT BOLD COMMENT
16 PRINT EXPANDED
17 PRINT EXPANDED OFF
18 PRINT EXPANDED COMMENT
19 PRINT ITALICS
20 PRINT ITALICS OFF
21 PRINT ITALICS COMMENT
22 PRINT RESET

The reference PRN NR is a numeric reference and therefore must have a significant length of eight. In the program the number has been limited to have a maximum of 5 digits (99,999). PRN NR, converted to a string, has a significant length of only five. So the significant length of index 2 could really be only 29. But please use 32 as the significant length of index 2.

Quickstart of PRAGMA

View Topic

QUICK START OF PRAGMA

If you are in a hurry or simply don't like to read manuals, these pages will give you the barest essentials on what you need to know to start using PRAGMA.

DOS

You must have a 386 machine with at least 4 MB of extended memory and DOS version 3.3 or higher. It is best to use DOS 5.0 or higher.

With DOS 5.0 don't load anything into high memory unless you use the system call function from within PRAGMA. Avoid whenever possible the EMM manager. It will slow down the extender.

Make sure that SHARE is installed and SET TERM=DOSMEM for color monitors or DOSMEMMONO for monochrome monitors.

Plug a PRAGMA parallel security device into an available parallel port. It is best if the port is unused. If you have to attach a printer to the security device, turn on the printer. Skip over this step if you are planning to use PRAGMA only in demo mode.

Create a new subdirectory on the hard disk and copy the executable filefrom the release diskettes to the newly created subdirectory.

Type DOSLOGIC and DOSUTIL. All the files necessary to run PRAGMA will automatically decompress.

Delete the two files DOSLOGIC.EXE and DOSUTIL.EXE in order to avoid accidentally overwriting your PRVOCAB file in the future.

Type PRAGMA and you will be at the START message.

If you need help, type <F1> to go to the online help.

OS/2

You must have a 386 machine with OS/2 version 2.0 or higher.

Put a statement in the CONFIG.SYS file that says IOPL=YES and SET TERM=OS2ANSI for color monitors or OS2ANSIMONO for monochrome monitors.

Plug a PRAGMA parallel security device into an available parallel port. It is best if the port is unused. If you have to attach a printer to the security device, turn on the printer. Skip over this step if you are planning to use PRAGMA only in demo mode.

Create a new subdirectory on the hard disk and copy all the files from the OS2 subdirectory on the release diskette to the newly created subdirectory.

Type PRAGMA and you will be at the START message.

If you need help, type <F1> to go to the online help.

UNIX

These instructions apply only for SCO Xenix 386 version 2.3.2 and SCO UNIX version 3.2.

As superuser, call the program custom and choose the option Add a Supported Product.

Follow the instructions and, when asked what you want to install, choose ALL in order to install the complete PRAGMA system on your machine.

Once the installation has completed without errors, shut the system down and start it again, but log in as a user this time from wherever you want to run PRAGMA.

All the necessary PFM files will be in a directory called usr/pragma, while all the other files will have been installed and given the proper permissions by the installation program custom.

Type pragma (lower case letters) and you will be at the START message.

If you need help, type <F1> to go to the online help.

DEMO MODE

If you start PRAGMA without a security device, PRAGMA will abort or will run in one of the two DEMO modes, depending on the parameter DEMO MODE in the description file PRAGMA.DES.

APPLICATION demo mode allows any size application to be demonstrated, but the system will bail out to the operating system after a certain amount of activity with a security error. All writing to the vocabulary is discarded.

LANGUAGE demo allows the PRAGMA language to be demonstrated, but the system will only start and run if the vocabulary is under a certain size. Within the vocabulary size limit everything is permitted.

In both demo modes the online help (type <F1> at the START message) is always accessible.

See also:

Operating Systems Overview

Record Locking

View Topic

RECORD LOCKING

Some form of record locking has to be implemented whenever more than one user has access to files. This situation can arise on a network or on a UNIX system.

To ensure the integrity of a database while working in a multiuser environment we must first consider what data corruption is and the possible causes.

Corruption of data is, in essence bad, or lost data. Consider this situation. Two users A and B are performing maintenance to the same inventory item record. The sequence of events goes as follows.

User A reads the item record, balance on hand is 20.
User B reads the item record, balance on hand is 20.
User A receives merchandise changing the balance on hand to 30.
User B records a sale changing the balance on hand to 10.
User A saves back the record. Balance on hand is 30.
User B saves back the record. Balance on hand is 10.

As you can see, the record of the merchandise received by user A is lost with no warning whatsoever of what happened. This is a very simple situation but it illustrates the basic problems caused by not having some sort of traffic control while accessing to the data.

To avoid a situation like the one described above you have to lock the record being used so that only one user at a time can access it.

RECORD LOCKING IN PRAGMA

The implementation of record locking in PRAGMA is basically very simple. Don't feel overwhelmed by the seemingly large number of verbs involved.

Record locking is accomplished automatically by the action of GETing a record in a file with a GET verb that LOCKS, as opposed to the normal GET that does not. Once you GET and LOCK a record, nobody else can access that record until you, and only you, unlock it with an UNLOCK verb.

There are two ways that you can lock a record: you can do it with a GET WAIT LOCK or with a GET NOWAIT LOCK.

A waiting GET (regardless of whether it also locks a record or not), will keep trying to read a record, and if it is locked by another user, will wait forever until it becomes free. There is no way to cancel this suspension otherwise.

A nonwaiting GET will try to read a record only once. If the record is locked by another user it will return immediately with the message "conflict" in EXTERNAL ECHO and a status of 3 in FILE STATUS. If, while using nonwaiting GETs, you encounter a locked record, and you wish to wait for it, you have to attempt your file operation again. You can continue doing so until you get sick of waiting or until the record becomes available. It should be noted that you should not do this in a tight and fast loop. Perhaps instead you should inform the user, and ask them to press a key to try again.

On multiuser systems (which is of course what you are using, and in need of locking for in the first place), each attempt to access the record will require some CPU time, and possibly disk activity as well. In the case of a locked record, this time is essentially wasted. On a UNIX system, this will slow down the system for everybody. On a network, this will slow down the network and the server.

To put it in another way, a waiting GET is the simplest way of implementing record locking and it minimizes CPU or network load. It has the disadvantage that a user might get impatient if someone else takes forever to update a record. A nonwaiting GET gives you more flexibility but it requires more programming and will put more of a burden on the hardware.

Normally, you will use a waiting GET if you know that you will always want to wait, however long, for a record if it is busy. You will use nonwaiting GETs if you may get tired of waiting, and could decide to do something else in the meantime instead of sitting around doing nothing until the locked record is free. If locked records can be processed quickly, the waiting time of a wait GET can be kept short. However, some circumstances may require a long lock time, and in these cases a loop with a nonwaiting GET is preferable. The loop can be exited then if some time limit expires and the record is still locked.

When a file is used with record locking, it is important that ALL accesses to this file are done with the locking verbs, whether you want to lock a record or not. Do not use the normal GET for a record that might be locked by another user, since it may or may not abide by the locks set by the lock verbs. How it acts is dependant upon the file manager being used and the operating system.

Since all the locking file words have the same syntax as the normal GETs, you can use EXCHANGE to substitute them for each other.

All lock commands are capable of locking multiple records in any number of files. There are no hard limits to the number of records that can be locked in any given file, nor in all files combined. Each such lock simply requires a small additional amount of memory space to add to the table of outstanding locks that PRAGMA keeps.

The operating system may however have a limit on the number of locks it can handle. This, in the case of UNIX, is a kernel parameter. You must edit and relink the kernel to allow more locks. In the case of DOS, it is a parameter to SHARE. There may also be limits imposed by a network. Btrieve also has a parameter to specify the maximum number of locks. All of these things are obviously (and unfortunately) beyond the power of PRAGMA to understand and you must ensure that your environment can support the number of locks that your application requires.

You may LOCK a particular file record only once. You may not stack up locks. There is only one lock per record; it is either locked or not. The first unlock encountered for this record thus clears this lock. You will receive a "duplicate reference" (file status 2) error if you ever attempt to lock a record more than once.

It may appear strange at first glance to receive "duplicate reference" during a GET. But this can be used to your advantage. Imagine a situation where a verb locks a file record. The verb then calls another verb, which also locks the same file record. The second verb, when it has finished its job, releases the file record and returns to the first verb. The file record is now unlocked, and the first verb may not know it. This situation can cause a lot of trouble.

The "duplicate reference" status you get in this case can be used to prevent this from occurring. The second verb may try to lock the record again, but when it gets this error, it will know that it must act differently. The second verb should then perform a normal GET without LOCK, and also refrain from UNLOCKing the record at the end. Thus, the record will still be locked when returning to the first verb.

Btrieve and PFM act slightly differently in regards to this reporting of multiple locks. PFM will recognize this condition before attempting to get the file record. The duplicate reference error will be reported, and the record will not be retrieved. Btrieve will not recognize this problem until after the record has already been retrieved. The error will be reported, but the record will actually have been read and placed into the nouns already, overwriting the old values. In either case, it is NOT a good idea to rely upon this fact. It is only being noted here for your information. If you ever get a duplicate reference error during a GET/LOCK, you should repeat the GET without a LOCK.

If you attempt to DELETE or SAVE THIS a file record that is locked by another user, your verb will either be suspended until the record is free, or the operation will fail immediately with a "conflict". What happens depends on the operating system and file manager. In general, it is very bad to go around deleting or updating records you do not own, so the best idea is to avoid this situation entirely. Only delete or update records that you have currently locked, unless you are positive that you are the ONLY user that is accessing them.

UNLOCKING A RECORD

There are three options to unlock a record. UNLOCK RECORD (and of course its companion EXTERNAL UNLOCK RECORD) will unlock a specified single record in a specified file. UNLOCK FILE will unlock all locked records in a single file. UNLOCK ALL will unlock all locked records in all files, but only files of the respective file manager.

It is only possible to unlock records that you have locked. You cannot unlock records locked by another user.

A record will also be unlocked if you delete it or update it (with SAVE THIS). A successful unlock will return an OK status to EXTERNAL ECHO, and a zero to FILE STATUS. If you try to unlock a record that is not locked, you will get a "record not found" in EXTERNAL ECHO, and a 1 in FILE STATUS. All records are also automatically unlocked whenever you perform a CLOSE ALL FILES, a SYSTEM CALL, a SET FILE PATH or SET EXTERNAL FILE PATH, and when you return to START.

The UNLOCK RECORD verbs also affect the file THIS pointer.

DEADLOCKS

An annoying situation can occur when user one is trying to get a record with a waiting GET that user two has locked and does not release. User two, who locked the record, may have gone home leaving the PRAGMA program in an edit screen, or something equally stupid. Of course user one will not be able to access the locked record.

This situation can only happen if waiting locks are used. With a nowait lock there is always the possibility of giving up and starting over, or doing something else. An application should make use of this.

If a situation becomes desperate, UNIX always gives the superuser the option to kill the offending user and thereby eliminating all his locks. When a PRAGMA program stops, by crash, by kill or whatever, UNIX removes all pending locks that are active.

A true deadlock happens if user one is attempting to do a wait lock, and the item he is attempting to lock is already locked by user two. He thus is put to sleep. But if user one already has a record locked, and user two now attempts to read the record locked by user one, both users will be put to sleep, forever.

UNIX checks for this kind of situation and will refuse the lock request by user two and issue a conflict . This is a special case for wait locks, since normally one never sees a conflict with a wait lock. If you get a conflict with a wait lock, you will know that a deadlock was about to happen and you can then take special measures to bypass it.

Deadlocks can be sidestepped by using nonwait locks and writing your programs in such a way that you are only allowed a certain amount of time to leave a record locked. If you cannot get everything you need done in the allotted time, an UNLOCK ALL is automatically issued, and you can then retry the whole thing again.

RECORD LOCKING AND UNLOCKING VERBS

The following verbs perform a lock during a GET:

Verb name Abbreviation

GET WAIT LOCK FIRST GWLF
GET WAIT LOCK NEXT GWLN
GET WAIT LOCK THIS GWLT
GET WAIT LOCK LAST GWLL
GET WAIT LOCK GWLK
GET NOWAIT LOCK FIRST GNLF
GET NOWAIT LOCK NEXT GNLN
GET NOWAIT LOCK THIS GNLT
GET NOWAIT LOCK LAST GNLL
GET NOWAIT LOCK GNLK
EXTERNAL GET WAIT LOCK FIRST XGWLF
EXTERNAL GET WAIT LOCK NEXT XGWLN
EXTERNAL GET WAIT LOCK THIS XGWLT
EXTERNAL GET WAIT LOCK LAST XGWLL
EXTERNAL GET WAIT LOCK XGWLK
EXTERNAL GET NOWAIT LOCK FIRST XGNLF
EXTERNAL GET NOWAIT LOCK NEXT XGNLN
EXTERNAL GET NOWAIT LOCK THIS XGNLT
EXTERNAL GET NOWAIT LOCK LAST XGNLL
EXTERNAL GET NOWAIT LOCK XGNLK

The following verbs do not perform a lock, but do abide by the locks of other users.

Verb name Abbreviation

GET WAIT FIRST GWF
GET WAIT NEXT GWN
GET WAIT THIS GWT
GET WAIT LAST GWL
GET WAIT GW
GET NOWAIT FIRST GNF
GET NOWAIT NEXT GNN
GET NOWAIT THIS GNT
GET NOWAIT LAST GNL
GET NOWAIT GNW
EXTERNAL GET WAIT FIRST XGWF
EXTERNAL GET WAIT NEXT XGWN
EXTERNAL GET WAIT THIS XGWT
EXTERNAL GET WAIT LAST XGWL
EXTERNAL GET WAIT XGW
EXTERNAL GET NOWAIT FIRST XGNF
EXTERNAL GET NOWAIT NEXT XGNN
EXTERNAL GET NOWAIT THIS XGNT
EXTERNAL GET NOWAIT LAST XGNL
EXTERNAL GET NOWAIT XGNW

The following verbs perform unlocking of records.

Verb name Abbreviation

UNLOCK RECORD UR
UNLOCK FILE UF
UNLOCK ALL UA
EXTERNAL UNLOCK RECORD XUR
EXTERNAL UNLOCK FILE XUF
EXTERNAL UNLOCK ALL XUA

PRAGMA 3 EMULATION (MOCK MODE)

The so called "mock" emulation mode (mock flag one or two) which simulates the PRAGMA 3 internal file manager and the PRAGMA Fileserver, still perform locks, if enabled to do so, as before. As before, only one record per user can be locked.

If up to now you have used a Btrieve or PFM lock file for software record locking, you do not have to change anything in your application, as PRAGMA still operate in these old ways for compatibility reasons.

Whenever you do a file access to a mock PFM or a mock Btrieve file with a GET or an EXTERNAL GET , and record locking is enabled in PRAGMA.DES, the particular record that you are accessing gets locked. If you encounter a locked record, your verb is suspended until the record is released. Doing another file operation (another GET for instance,) releases that particular record or you can do a RELEASE or an EXTERNAL RELEASE to accomplish this.

Similarly, whenever you do a file access with EXTERNAL GET to the Fileserver, the particular record that you are accessing gets locked. Doing another file operation releases that particular record or you can do an EXTERNAL RELEASE to accomplish this.

The option DISABLE RECORD LOCKING in the REMOTE WORK menu of the Fileserver lets you disable automatic record locking. If you disable the record locking ability of the Fileserver you must implement in your software a record locking mechanism to avoid possible conflicts.

The standard verbs RELEASE and EXTERNAL RELEASE, the INTERNAL RECORD LOCKING and EXTERNAL RECORD LOCKING key words in PRAGMA.DES apply ONLY to the here described mock emulation mode. They should not be mixed with the regular lock verbs.

Reference Files PRAREF-PRAREF2

View Topic

REFERENCES EDITOR

This section lets you change or edit the online help files, PRAREF.PFM and PRAREF2.PFM.

The file PRAREF.PFM is the file that is used by PRAGMA for the PRAGMA references. It contains one record for every standard, including a short description.

Since some standard verbs require more explanation, that explanation, which can be as long as necessary, is stored in the file PRAREF2.PFM as a text file. You cannot directly edit the text contained in PRAREF2, as it may be several pages long. Instead, you can export or import the text to the operating system, where it can be edited with a word processor. All the records that refer to standards have the same number as the standard ID number.

PRAREF2.PFM also contains all the online help text for PRAGMA, the PRAGMA SCREEN GENERATOR and other programs related to PRAGMA.

PRAREF.PFM contains the following information:

REFERENCE NUMBER
REFERENCE NAME
REFERENCE ABBREVIATION
DATE OF LAST UPDATE
REFERENCE WHAT IS IT
REFERENCE OPERATION PERFORMED
REFERENCE USE
REFERENCE FORMAT
REFERENCE SEE ALSO
REFERENCE TARGET NOUN
REFERENCE MORE

REFERENCE NUMBER identifies a reference and must be the same number as the standard's ID number. REFERENCE NAME and REFERENCE ABBREVIATION must be the same as the standards name and abbreviation.

DATE OF LAST UPDATE is the date this particular reference was last changed.

REFERENCE WHAT IS IT tells you whether the reference is a standard verb, noun or a standard interactive-use only verb.

REFERENCE OPERATION PERFORMED tells you what kind of action the standard performs.

REFERENCE USE gives a short description (maximum 6 lines on the screen) of what this standard does.

REFERENCE FORMAT tells you how to use the standard (maximum 6 lines on the screen).

REFERENCE SEE ALSO are three fields which refer you to other references containing related information.

REFERENCE TARGET NOUN lists the target noun or nouns, if any, that are used by this standard.

REFERENCE MORE tells you whether there is another screen of this reference with more information. This information would be in the file PRAREF2.PFM.

PRAREF2.PFM contains the following information:

REFERENCE 2 NUMBER
REFERENCE 2 GROUP
REFERENCE 2 NAME
DATE OF LAST UPDATE
REFERENCE 2 TEXT
REFERENCE 2 NUMBER OF LINES

REFERENCE 2 NUMBER identifies a reference and for numbers smaller than 1000 must be the same number as the standards ID number.

REFERENCE 2 GROUP is a number that is common to related references. For instance, all the additional online help messages of PRAGMA belong to group 3.

REFERENCE 2 NAME for numbers smaller than 1000 is the same as the standards name. For numbers above 1000 it is the title of the online help text.

DATE OF LAST UPDATE is the date this particular reference was last changed.

REFERENCE 2 TEXT contains the actual text describing references for numbers below 1000 and online help for numbers above 1000.

REFERENCE 2 NUMBER OF LINES contains the number of dispaly lines of a text. This information, if present, is not used.

DISPLAY, EDIT ORDELETE A REFERENCE

ID # is the number of the record and it corresponds to the
standard ID number or the help message number.
It should not be changed.

What tells you what the standard is. The <UP ARROW> and
is it <DOWN ARROW> keys will change the selection.

What tells you what the standard does. The <UP ARROW> and
it does <DOWN ARROW> keys will change the selection.

See also These three fields refer you to other references, which
may contain related information. You may fill only one
field, entering a space into the others. But if you
enter information, it MUST be the correctly spelled
name of a reference contained in this file.

Target is the name of the target noun or nouns a standard may
noun write to. Enter a space if it is not used.

More This field tells the user whether there is a matching
record in the file PRAREF2. It must contain either a Y
or a N. Only if this field contains a Y will the
program be able to access the additional reference file.

To display, edit or delete a reference, you first have to enter the number or the first letters of the name of the reference that you want to see and edit. After having done so, the record chosen will be displayed. If you want to see a different record, you may proceed to the next one or the preceding one by hitting the up or down arrow keys.

Hitting the <F7> key lets you edit the record. The first field will be lighted and ready to be edited. To proceed to the next field hit <TAB>, to go back one field, hit <SHIFT-TAB>. <ESC> terminates the editing mode and saves the changed record. To abort hit <SHIFT-F10>.

The <F8> key lets you delete a record. You are given a last chance not to proceed before irreversibly deleting the displayed initialization. After deleting a record the next record will be displayed.

The <F6> key lets you print the reference.

NEW REFERENCE

Lets you create a new reference. To abort hit <SHIFT-F10>.

This option should really not be used, unless you have accidentally deleted a reference.

LIST ALL REFERENCES

Three choices are available.

The first choice is whether to display the listing on the screen or to make a printout. The second choice asks you where you want to begin the list and the third choice asks you where you want to end it. Default lists on the screen all the records in alphabetical order.

If you wish to access the records numerically, just enter the numbers indicating where you want the list to begin and end.

To proceed to the next choice use the <TAB> key.

When listing on the screen, one record will always be highlighted. By using the <UP> and <DOWN> arrow keys you can move the highlighting up and down. Hitting the <F9> key will display the record that is highlighted.

DISPLAY, EDIT A REFERENCE 2

Reference is the number of the record and it corresponds to
2 # the standard ID number for records with numbers
below 1000. It should not be changed.

Reference is the group number the recor belongs to.
2 group

Reference is the name of the record and it corresponds to the
2 name standard name for records with numbers below 1000.
For the help text it is the title of the help.

Reference is the number of display lines a text consists of.
2 number Not used at present.
of lines

To display, edit or delete a reference 2, you first have to enter the number or the first letters of the name of the reference that you want to see and edit. After having done so, the record chosen will be displayed. If you want to see a different record, you may proceed to the next one or the preceding one by hitting the up or down arrow keys.

Hitting the <F7> key lets you edit the record. The first field will be lighted and ready to be edited. To proceed to the next field hit <TAB>, to go back one field, hit <SHIFT-TAB>.

When you reach the field that contains the reference or the screen, you have three choices. If you want to export the contents of the field to a textfile on the operating system for editing, enter an operating system file name and immediately hit the <F3> key. If you want to import from the operating system a text file you enter the filename and hit the <F2> key. If you want to import a screen from the SCREEN.PFM file you enter the number of the SCREEN.PFM file and hit the <F4> key. This last option is not really used since normally all the records contain only text and not screens. <ESC> terminates the editing mode and saves the changed record. To abort hit <SHIFT-F10>.

The <F8> key lets you delete a record. You are given a last chance not to proceed before irreversibly deleting the displayed initialization. After deleting a record the next record will be displayed.

The <F9> key lets you see the contents of the reference.

The <F6> key lets you print the reference.

NEW REFERENCE 2

Lets you create a new reference 2. To abort hit <SHIFT-F10>.

If you want to add additional text to a reference you use this option. Remember that if you add text to a reference you most change the "more" option in the corresponding PRAREF file to a Y.

The importing and exporting of text files is the same as when editing.

LIST ALL REFERENCES 2

Three choices are available.

The first choice is whether to display the listing on the screen or to make a printout. The second choice asks you where you want to begin the list and the third choice asks you where you want to end it. Default lists on the screen all the records in alphabetical order.

If you wish to access the records numerically, just enter the numbers indicating where you want the list to begin and end. To proceed to the next choice use the <TAB> key.

When listing on the screen, one record will always be highlighted. By using the <UP> and <DOWN> arrow keys you can move the highlighting up and down. Hitting the <F9> key will display the record that is highlighted.

PRINT IN FULL ALL REFERENCES

Three choices are available.

The first choice is whether to print in full all the references (PRAREF and PRAREF2) or only PRAREF or PRAREF2.

The second choice asks you where you want to begin the list and the third choice asks you where you want to end it. Default prints all the records of PRAREF in alphabetical order starting with $INPUT. Remember that the first record in an alphabetical listing does not necessarily start with A. Non-alphabetical characters like $, come first. The program only accepts upper case characters if the description file contains the parameter LOWER TO UPPER CASE = YES.

If you wish to print all the records in numerical order, just enter the numbers indicating where you want the printout to begin and end.

To proceed to the next choice use the <TAB> key.

HINT: To find out the record number of a help screen, do the following. When entering the online help or another PRAGMA program and the program waits for any key to continue past the copyright screen, enter a "D" (capital D) When displaying the first screen of a help text, the record number is displayed in the upper right corner of the screen.

RECORD #999 contains information on when the file was last updated. This information is used by the PRAGMA online help in the PRAGMA system option.

ACCESSING THE FILES

The following section describes how to access the PRAGMA reference files from PRAGMA

To access the PRAGMA editor files you must have a PFM NUMERIC REFS = YES statement in your description file.

This is the file definition of PRAREF.PFM.

RECAP the definition of PRAREF

The short name is PRAREF
The Btrieve open mode is 0
The PFM unit size is 256
The mock flag is 0
The number of indexes is 1
The significant length of index 1 is 0

1 REF KEY (index selection noun)
2 REF ID NR (reference 1, 5 bytes, padded
with leading spaces)
3 REF NAME (reference 2, 31 bytes, padded)
4 REF ABBREVIATION (reference 3, 7 bytes, padded)
5 REF WHAT IS IT (reference 4, 60 bytes, padded)
6 REF OP PERFORMED (reference 5, 60 bytes, padded)
7 REF LAST UPDATE (reference 6, 6 bytes, padded)
8 REF USE 1 (the following are regular nouns
78 bytes max)
9 REF USE 2
10 REF USE 3
11 REF USE 4
12 REF USE 5
13 REF USE 6

14 REF FORMAT 1
15 REF FORMAT 2
16 REF FORMAT 3
17 REF FORMAT 4
18 REF FORMAT 5
19 REF FORMAT 6
20 REF SEE ALSO 1 (regular nouns, 31 bytes max.)
21 REF SEE ALSO 2
22 REF SEE ALSO 3
23 REF TARGET NOUN (regular nouns, 60 bytes max.)
24 REF MORE (1 byte, a Y or a N)

This is the description file used to generate an empty PRAREF.PFM file:

PRAREF.DES

page=512
key=6
position=4 (REF ID NR)
length=5
segment=n
position=12 (REF NAME)
length=31
segment=y
position=4
length=5
segment=n
position=46 (REF ABBREVIATION)
length=7
segment=y
position=4
length=5
segment=n
position=56 (REF WHAT IS IT)
length=60
segment=y
position=4
length=5
segment=n
position=119 (REF OP PERFORMED)
length=60
segment=y
position=4
length=5
segment=n
position=182 (REF LAST UPDATE)
length=6
segment=y
position=4
length=5
segment=n

This is the file definition of PRAREF2.PFM.

RECAP the definition of PRAREF2

The short name is PRAREF2
The Btrieve open mode is 0
The PFM unit size is 1024
The mock flag is 16
The number of indexes is 4
The significant length of index 1 is 8
The significant length of index 2 is 40
The significant length of index 3 is 11
The significant length of index 4 is 42

1 REF2 KEY (index selection noun)
2 REF2 ID NR (reference 1, unique number)
3 REF2 NAME REF (reference 2, 35 bytes, obtained
by joining REF2 NAME in front of
REF2 ID NR)
4 REF2 LAST UPDATE REF (reference 3, 6 bytes, obtained
by joining REF2 LAST UPDATE in front of
REF2 ID NR)
5 REF2 GROUP REF (reference 4, 3 bytes, obtained
by joining REF2 GROUP in front of
REF2 ID NR)
6 REF2 NAME
7 REF2 LAST UPDATE
8 REF2 GROUP
9 REF2 TEXT
10 REF2 NR OF LINES

Room for Improvement

View Topic

ROOM FOR IMPROVEMENT

Things can always be made better, faster or more powerful. But some things take time, others may be to the detriment of other features. The following listing of known problem areas shows you that we are aware of what may be some of your complaints.

CONTROL C

Under UNIX, the <CONTROL-C> pause/abort key will sometimes cause the screen to be messed up a bit. If the keypress interrupts an output in progress to the screen, the output may be discarded. Sometimes, this may be a control sequence to the screen, and you will see a few garbage characters on the screen if it is not properly completed. Also, the cursor position may become corrupted. A CLEAR SCREEN will always fix this. Discussions with SCO are pending regarding this issue.

Also, under DOS, a ^C is output whenever <CONTROL-C> is pressed, and it too will mess up the screen and cursor position. Anybody who knows how to prevent DOS from displaying this silly message to the screen will get a DOS hacker of the year award.

LISTINGS

At this moment listings (LIST VERBS, LIST NOUNS, etc.) are slow by design. That may sound bad, but it is true. PRAGMA 3 has a segmented vocabulary index. It is faster, but more complex. The index is sorted not only by the name of the item, but also by data type. All verb names are contiguous, as are all files and nouns. This makes listing faster, but everything else is more complex, like searching, or inserting. We decided that all of that extra trouble was not worth the effort at this moment. We put the vocabulary index in pure alphabetic order, and all nouns, files, and verbs are together and not separated. This is exactly the way ADAM I and TINA were. The reason it is slower is because it has to skip over all of the items of the incorrect type when you are listing something. The availability of boundaries for a listing should help a bit.

TRACE AND FORGET

Also TRACE and FORGET are slow, due to the design of PRAGMA 4.

You can help TRACE by using the delimiters, if that is possible.

Instead of using FORGET simply rename the culprit or don't worry about it. Once a week you should clear out the unwanted stuff from the vocabulary, using the SELECTIVE SAVE verb.

Running PRAGMA on DOS

View Topic

RUNNING PRAGMA ON DOS

If your environment has been set up correctly and all the necessary files are present, the last item to check is whether you have the correct parameters in the PRAGMA.DES file. PRAGMA.DES is a text file that contains various user definable parameters.

The easiest way to check PRAGMA.DES is to enter the online help from the START prompt (hit the F1 key) and access the CHOICES menu.

Apart from that, there are no other particular recommendations for running PRAGMA under DOS.

To pause a PRAGMA application you press either the <CONTROL-C> or <CONTROL-BREAK> keys twice (in many cases you must then also hit a <RETURN/ENTER>). This will get you into the debugger, which tells you, among other things, where in the program you stopped. To resume the application press <RETURN/ENTER> from the debugger command window. To abort type ABORT EXECUTION (AEX). Whenever you pause an application in this way an entry into the PRAGMA.LOG file is made. If the debugger has been disabled, pausing an application as described above will get you back to the start prompt.

For <CONTROL-BREAK> or <CONTROL-C> to be effective while listing or doing recaps, you must have a statement BREAK=ON in the CONFIG.SYS file.

The difference between <CONTROL-C> and <CONTROL-BREAK> is that <CONTROL-BREAK> will flush out the keyboard buffer and issue an immediate interrupt, and therefore you get an immediate response. <CONTROL-C> is put into the keyboard buffer and no immediate interrupt is issued. But sooner or later the keyboard input routine, when reading the keyboard buffer, will notice the <CONTROL-C> and then issue an interrupt. Unfortunately DOS has the annoying habit of displaying the characters "^C" followed by a carriage return and a linefeed whenever a <CONTROL-C> or a <CONTROL-BREAK> are processed.

You must never use the abort or ignore options of the abort/retry/ignore message displayed by DOS. These options could upset the DOS extender. This DOS message could be displayed under various circumstances, such as when your printer has not been selected. But in all cases always use "retry".

Always exit PRAGMA with the terminating key from the START message. Improper termination, like simply turning the computer off, can cause file corruption and loss of data.

See also:

Running PRAGMA on Networks
Installing PRAGMA on DOS

Running PRAGMA on Networks

View Topic

Running PRAGMA on OS/2

View Topic

Running PRAGMA on UNIX

View Topic

RUNNING PRAGMA ON SCO UNIX

To start PRAGMA simply type "pragma", but remember that it must be entered in lower cases.

To pause a PRAGMA application you press either the <CONTROL-C> or <CONTROL-BREAK> keys twice (in many cases you must then also hit a <RETURN/ENTER>). This will get you into the debugger, which tells you, among other things, where in the program you stopped. To resume the application press <RETURN/ENTER> from the debugger command window. To abort type ABORT EXECUTION (AEX). Whenever you pause an application in this way an entry into the PRAGMA.LOG file is made. If the debugger has been disbled, pausing an application as described above will get you back to the START prompt.

<CONTROL-C> always generates an immediate interrupt regardless what data is in the keyboard buffer. Do not leave a terminal paused for long periods of time. When in a paused state the program will be in a tight loop and be very wasteful of CPU time. Everybody else on the system will hate you.

Never type a backslash (\) when under UNIX. This command tells UNIX to immediately shut off the particular program it is running (in our case PRAGMA), which can cause file corruption and loss of data.

Always exit PRAGMA with the terminating key from the START message. Improper termination, like simply turning the computer off, can cause file corruption and loss of data.

PATHS

UNIX has a path command like DOS, but UNIX looks for executable files ONLY in the path. DOS first looks in the default directory, UNIX does NOT. To see what path you have set, type env at the operating system prompt.

PRINTING

DOS, like most normal operating systems, wants both a carriage return and a line feed character (^M^J) to mark the end of a line. When UNIX was born some higher authority decided to simplify things and therefore only line feed character (^J) is needed to mark the end of a line, thereby causing a royal pain you know where when you have to go from one operating system to the other. In UNIXese this character is referred to as a new line character.

PRAGMA, being born of normal origins, of course uses both the carriage return and line feed characters to terminate a line. And so does every PRAGMA program ever written. They will have PRINT "^M^J" everywhere.

The way the print logic is done for PRAGMA under UNIX, PRAGMA will open the device specified in the description file (something like /dev/lp0) and will send the print data to it verbatim. The printer will get the carriage return/line feed sequence it needs and all is well.

To use the UNIX printer spooling, a PRAGMA application must contain the necessary logic to inform UNIX to activate the spooler. A description of how to do this is contained in the UNIX - Printing section of the online help.

PRAGMA under UNIX supports a printer for each user. But if you want more than one user to a printer, you must have a mechanism in your code to lock the printer while it is being used by another user. Otherwise, you will get interleaved printing. A simpler way to share printers is to always print using the UNIX spooler, thus avoiding this problem.

RUNNING MULTIPLE USERS

In UNIX all users who will be using the same PFM files and running the same PRAGMA program need to belong to one group.

You should make a directory for the purpose of the group's work. In this directory, place all the PFM files, plus the PRAGMA program, the .DES file, and everything else you need. This directory MUST be given read, write, and execute permission for everyone in the group. All of the files in it must also be given read and write permissions for the group, if they do not already have it. In other words, make a big place for everyone to share all of this stuff, put it all in there, and give everyone in the group permission to use it. Then, each user who is a member of this group will change into this directory to do his work. They will ALL run the EXACT SAME PRAGMA program. UNIX will load only one copy of this program in memory, and all users will share it. This will save memory.

You must give read/write permission to your PFM files, because all PFM files are always opened in read/write mode. If write permission is denied, the opening will fail and PRAGMA will return a NO SUCH FILE status.

When running PRAGMA in a multiuser environment you cannot write back to disk the contents of the changed nouns (which means that the parameter WRITE NOUNS in pragma.des is not allowed to be on) and share the vocab with another user. If you want to use the noun value writeback option, you must give each user a separate PRVOCAB in a separate directory. You can do this and still share the other files using the UNIX link command.

TERMINALS

You may use either dumb terminals or a PC running a terminal emulation program.

With dumb terminals the performance and capabilities of PRAGMA depend on how smart the terminal is and with what baud rate it has been connected to the computer running UNIX.

If you choose a PC as a terminal you should use the terminal emulator program P4TERM that runs under DOS and is designed specifically to act as a terminal for PRAGMA. Many of the PRAGMA 4 commands (particularly when using PRAGMA windows) are handled much faster with P4TERM than on a dumb terminal or a conventional terminal emulator program.

For complete instructions on how to connect terminals and run PRAGMA please consult the various entries in the online help.

RECORD LOCKING

Remember that in a multiuser environment some form of record locking must be in effect.

FILE TRANSFER FROM DOS

To transfer PFM files from DOS you use the following doscopy command, assuming the files reside in the PRAGMA subdirectory on drive C:

doscopy c:/pragma/*.pfm . -r

Because the PFM files are binary, not text, and because you don't want to take out the CR, you must add the -r option.
The filename must stay capitalized.

For the pragma.des file, again, use doscopy, but use the -m -x option since it is a text file. The filename must be in small letters.

Both files will be rw only (read write) and not x, since they don't have to be executable.

For an in-depth explanation of the doscopy utility please consult the UNIX - Doscopy Utility section of the online help.

See also:

Running PRAGMA on Networks
Installing PRAGMA on SCO UNIX
UNIX - Doscopy Utility
UNIX - Printing
UNIX - Terminals
UNIX - Differences

SCREEN HELP 5000 - 5999

View Topic

SCRNCAP Utility

View Topic

Save - Be Careful

View Topic

Saving a Window

View Topic

Saywhat Screen Generator

View Topic

Saywhat to Screens Converter

View Topic

FILE MENU - SAYWHAT TO SCREENS CONVERTER

The SAYWHAT to SCREENS converter automatically converts SAYWHAT squeeze files into PRAGMA compatible files and saves them into the file SCREENS.PFM. It can only be run under MS-DOS.

Only regular SAYWHAT screens can be correctly converted. Screens that contain menus will be converted, but of course will lose the menu capability. Any control character encountered will be simply accepted, even if it may result in something different in PRAGMA.

Put all your SAYWHAT squeeze files into an empty directory on your hard disk. The files must not be stored in a library. Do a directory listing with the command DIR. All the files will be converted and saved in the SCREENS.PFM file in the same sequence. You will not be able to select files or change their sequence during conversion, so if you want to exclude some or sort them in another way, this is the moment to it.

Set the environment variable TERM to DOSANSI or DOSANSIMONO. DOSMEM or DOSMEMMONO will not work.

Make sure that you have as much free memory available as possible. The program will do system calls and they will not work if there is not enough lower memory. So get rid of Btrieve, network drivers and similar programs.

Load the TSR program VIDPOP into memory. The wake up characters must both have a value of 255 decimal, the default value for VIDPOP. If you are in doubt about the character used by your VIDPOP, look at the copyright notice when VIDPOP is first loaded. You must also send VIDPOP the necessary parameters, like SET STATUS BOTTOM, for instance. Otherwise your windows may end up in the wrong position.

In the directory where you are running PRAGMA you must have the utilities FILEUTIL.EXE and SCRNCAP.EXE. Both can be found on the PRAGMA DOS release diskettes.

If any file is missing, the program will tell you. But be aware that the program does not check if VIDPOP has been loaded into memory.

In PRAGMA go to the online help (<F1> key) and access the FILE menu of the screen generator. Choose the Convert Saywhat option. This will start the conversion program.

Once all the necessary files are present, you must indicate the directory (and drive if necessary) where you have put the squeeze files. If they all are in the same directory as PRAGMA, simply hit <RETURN/ENTER>.

Then select with the bar menu whether you will allow the conversion of windows or not. If you choose this option, the program will determine where the window starts and ends and save these parameters in the SCREENS.PFM file, together with the window. For this option to work, you must have in the SCREENS.PFM file, as record number 10 a full screen completely filled with the same character. Any character will do, as long as it does not appear anywhere on your screens and windows. The SCREENS file, as shipped, contains as record number 10 a screen filled with the character 244 decimal.

The conversion program will count how many squeeze files are present and then give you the option to enter a different starting record number in the file SCREENS.PFM. The number displayed by the program is the next number after the last record. You can choose any number you want between 1 and 99,999, as long as there are enough free numbers to contiguously accommodate all the new records that are generated. The program does not let you choose a number that does not have enough free numbers ahead of it.

Hitting <RETURN/ENTER> at this point will start the conversion of the squeeze files. As the conversion proceeds, each Saywhat screen is first displayed by VIDPOP and then by PRAGMA, and is then saved into the file SCREENS.PFM in the same way a screen generator screen is saved.

The name of the squeeze file, without the suffix SQZ, is the name used for the SCREENS.PFM record.

A converted SAYWHAT full screen can be displayed by a simple DISPLAY command. A converted window must be displayed by first placing the cursor in the position where the left upper corner of the window will be. The SCREENS.PFM file contains this information. Consult the Screen Generator online help entry "Accessing the File SCREENS.PFM" for further details.

SAYWHAT and VIDPOP are trademarks of Software Science Incorporated.

See also:

Saywhat Screen Generator
SCRNCAP Utility
Accessing the File SCREENS.PFM - PRAGMA Screen Generator

Securing an Application

View Topic

SECURING AN APPLICATION

PRAGMA lets you secure your application against unauthorized running by purchasing from us a security device that contains a special number reserved for you. You can then incorporate into your program verbs that read the numbers present in the security block. If the read numbers are not the ones the program expoected, you can abort the application or do whatever you want.

The standard verb that lets you read your security number is called READ SECURITY VALUE (RSV). It can check nine locations in the security block memory, which can be programmed by us with whatever you want. You cannot write to the security device under any circumstances.

Location zero is the serial number of the block. This is preset by us and each block is different. The serial number is also printed on the sticker attached to the block. You have no control over this number, but you can use it to serialize your applications, if that is desired.

Locations one through eight can contain any number you want, but you must tell us when ordering a block what you want there. Otherwise all eight numbers will be zero.

The verb READ SECURITY VALUE takes two parameters; the security location to read (0-8) and the noun into which the number is written. You can then check the read number for equality or for a range.

User verbs, spread randomly about the system, can periodically call READ SECURITY VALUE. It is important to put a lot of these calls all over the application. Don't call these verbs too many times in a row, as that will slow things down, just place them in a lot of locations, like land mines.

The verbs RECAP and RECAP ALL skip over any line in any verb where READ SECURITY VALUE is used, and TRACE, EXCHANGE and EXCHANGE ALL refuse to trace it. TRANSLATE TO C refuses to translate any applications that contain READ SECURITY VALUE. The only place where READ SECURITY VALUE is visible is in the editor.

To further enhance the security of a secured application you can render the names of the verbs that contain READ SECURITY VALUE invisible with the verb REMOVE NAMES. REMOVE NAMES generates new names that are not only invisible, but also untypable and totally invalid in all places where an item name is requested.

WARNING

REMOVE NAMES is a completely and totally IRREVERSIBLE process. Always keep a backup of your application before rendering your names invisible!

Security Devices

View Topic

SECURITY DEVICES

The security device that provides security for PRAGMA and the applications written in PRAGMA may be attached to any parallel port (LPT1 through LPT3). If there is also a printer attached to the same port after the security device, it must be powered on. If possible attach the device to an unused parallel port. Security devices are supposed to be 100% invisible, but if they were 100% transparent they could not provide security.

No security device is needed to run PRAGMA utility programs.

Should you experience difficulties in reading the security device, try changing the time delay for accessing the security device in the parameter file PRAGMA.DES. This is done by entering a line called BLOCK TIMING DELAY = XXX, where XXX is a number between 1 and 200. Since the default value is 77, a higher number than 77 should be used.

Never connect a printer to the security device if you want to use the printer with a print spooler, as that could damage the security device.

For other UNIXES and minicomputers running their own dialect of UNIX a serial security device is attached to a serial port. This serial security device can also be used for SCO UNIX, DOS or OS/2. In this case a SECURITY statement in PRAGMA.DES has to tell PRAGMA the location of the security device. The serial security device must have a port all to itself.

For the Novell network there is a special runtime network security device attached to the parallel port of the dedicated server.

PRAGMA SECURITY TYPES

There are 9 different types of security devices that you can buy from us:

SCO UNIX MASTER DOS MASTER
SCO UNIX PROGRAMMABLE DOS PROGRAMMABLE
SCO UNIX RUNTIME DOS RUNTIME

NOVELL NETWORK RUNTIME

UNIX MINI PROGRAMMABLE
UNIX MINI RUNTIME

This list reflects the hierarchy of the devices. A MASTER is hierarchically higher than a PROGRAMMABLE or RUNTIME device, both in UNIX and DOS.

SCO UNIX devices are, for the same level, hierarchically higher than a DOS device. Therefore a SCO UNIX PROGRAMMABLE, for instance, will work both for SCO UNIX and DOS, but not the other way around.

The DOS security devices are valid for DOS and OS/2. The DOS devices will also work for PRAGMA 3 version 3.73 or higher.

The Novell network devices are intended to work only with a Novell network with only one device attached to the network server.

The SCO UNIX devices are intended to work with the Santa Cruz Operation version of Xenix and UNIX.

The UNIX MINI devices are both programmable and runtime serial security devices which are used when PRAGMA is compiled to a dialect of UNIX other than SCO UNIX, but they can also be used for SCO UNIX, DOS and OS/2.

MASTER SECURITY DEVICE

This is hierarchically the highest security device. With it you can run everything the other devices do. Both UNIX and DOS MASTER devices will also run PRAGMA 3, version 3.67 and higher. Both MASTER devices will also run PRAGMA Fileserver version 4.11 or higher.

The device is intended for program developers or users who use different pieces of PRAGMA on the same machine and don't want to be bothered with changing devices all the time.

PROGRAMMABLE SECURITY DEVICE

To be able to run and program in PRAGMA you must have a PROGRAMMABLE or a MASTER device plugged into your parallel printer port. If the device is absent you will default to the PRAGMA demo mode, if it has been enabled. If after having started PRAGMA you take away the device, you may expect difficulties.

PRAGMA 4 PROGRAMMABLE devices will also run PRAGMA 3, version 3.74 and higher.

RUNTIME SECURITY DEVICE

With the RUNTIME device plugged into your parallel printer port, you can run any PRAGMA program in runtime mode. The RUNTIME device will also run any compiled PRAGMA program.

When starting PRAGMA with a RUNTIME device you can indicate in the command line the first verb that you want to execute. If you omit the name of the starting verb, PRAGMA will look for a verb called AUTOEXEC and execute it. If it cannot find that verb PRAGMA will go back to DOS.

You will not be able to write programs in PRAGMA with a RRUNTIME device.

PRAGMA 4 RUNTIME devices will also run PRAGMA 3, version 3.74 and higher.

UNIX MINI SECURITY DEVICES

To run PRAGMA under UNIX you can also use a serial security device. It is available as a RUNTIME or as a PROGRAMMABLE version.

To use a serial security device you must attach it to an unused serial port. PRAGMA will automatically set the baud rate of 9600, 8 bits/character, no parity. The port must be DISABLED for login and the security device MUST have a port all to itself. In pragma.des you must put the line SECURITY = portname, where portname is the UNIX device name for the port (example /dev/tty1a), in order to tell PRAGMA where to look.

You must also give everybody read and write permission for the port device node to which the serial device is connected. Usually this is found in the /dev directory and the name will be ttyxx.

NOVELL NETWORK SECURITY DEVICE

The network security device is of the runtime type and lets you run PRAGMA programs on a Novell network with only one device attached to the network server.

The PRAGMA security code will first check for a network block connected to any parallel port of the local computer. If none is found, the network is polled.

Being a runtime device you cannot program from a workstation. Should you wish to program you must attach a programmable security device to the parallel port of the computer you intend to use for programming.

The network security device is available for 5, 10, 25, 50 and unlimited number of users.

The network security device works only with Novell Netware version 3.12 and 4.0 or higher. Also it will not run on Netware 4.0 or higher if Netware is running in protected mode. It will run OK if Netware is running in real mode.

INSTALLING A NETWORK SECURITY DEVICE

The network version of PRAGMA uses a separate PRAGMA.EXE file, available from Logical when you purchase a Novell network security device.

The PRAGMA Novell Network diskette contains the following files:

PRAGMA.EXE
NSLDR.EXE
NWSRVR.RBO
DOSMON.RBO

PRAGMA.EXE
The PRAGMA Software Development System that contains part of the interface to the network security device.

NSLDR.EXE
The loader program that contains the interface to the network security device.

NWSRVR.RBO
The file that contains the server program.

DOSMON.RBO
The file that contains a program to test the communications to the server.

Follow these instructions to install the security software on a Novell network:

1 Rename the file NWSRVR.RBO to be NWSRVR.EXE and then run it.
It will unpack itself.

2 The file NSRVNI32.NLM is the server program.
Copy it to the Novell server, to the directory where
all the other NLM's are.

3 Connect the network security device to a parallel port
of the server.

4 Run the security server program by typing the command:

LOAD NSRVNI32.NLM

The file AUTOEXEC.NCF may be modified to cause this
to happen automatically upon bootup of the server.

5 Copy the network PRAGMA.EXE and NSLDR.EXE to the
directory where you are running PRAGMA.

6 Run the loader by typing the following command:

NSLDR DOS4GW PRAGMA

This command presumes that you have a verb called
AUTOEXEC in PRAGMA (remember that the network security
device is runtime only). If you wish to start your
program with a different verb, you must add its name
to the command line, like this:

NSLDR DOS4GW PRAGMA VERBNAME

7 Run your PRAGMA program in the usual way.

We recommend that you make a batch file to start PRAGMA so that a user will not forget to run the loader before PRAGMA.

SECURING YOUR OWN APPLICATION

You may have just written the world's greatest PRAGMA application and you want to be sure that no one else with a PRAGMA security device can run your application.

To help you with this problem we can embed in any of the PROGRAMMABLE or RUNTIME devices that you purchase a special number that will be uniquely yours.

PRAGMA lets you check from within your application whether the security device contains your specific numbers.

But remember that you must tell us the special number when you order the security devices. Neither you nor anybody else will be able to add, change or delete this special number from the device.

PROBLEMS WITH THE SECURITY DEVICES

Nothing is perfect, not even security devices. The most common problem that can happen is that the system does not recognize the device if no printer is attached to the device. Usually if you attach a printer after the device and turn it on, the device will be recognized. This cumbersome way of solving the problem is due to the fact that your printer card is not 100% IBM compatible. Instead of connecting a turned on printer, you can try to jumper pins 10 (ACK) and 16 (INIT) on the female side of the device (the side that goes to the printer).

See also:

Securing an Application

Selecting the Screen Size

View Topic

Standards File PRSTD

View Topic

STANDARDS EDITOR

This selection lets you change or edit the PRAGMA standards file, PRSTD.PFM.

The file PRSTD.PFM is the file that is used by PRAGMA for all the standard verbs and nouns. These names can be changed or translated to another language.

The PRSTD.PFM file contains the following information:

STANDARD NAME
STANDARD ABBREVIATION
STANDARD IDENTITY NUMBER

STANDARD IDENTITY NUMBER identifies a standard. PRAGMA looks for a standard with this number.

STANDARD NAME and STANDARD ABBREVIATION are the name and abbreviation that you use in the PRAGMA definition editor.

DISPLAY, EDIT OR DELETE A STANDARD

Identity is the standard ID number. PRAGMA looks for the
Nr. standards by this number. You should not change it.

To display, edit or delete a standard, you first have to enter the number or the first letters of the name of the standard that you want to see and edit. After having done so, the record chosen will be displayed. If you want to see a different record, you may proceed to the next one or the preceding one by hitting the up or down arrow keys.

Hitting the <F7> key lets you edit the record. The first field will be lighted and ready to be edited. To proceed to the next field hit <RETURN/ENTER>, to go back one field, hit <SHIFT-TAB>. <ESC> terminates the editing mode and saves the changed record. To abort hit <SHIFT-F10>.

The <F8> key lets you delete a record. You are given a last chance not to proceed before irreversibly deleting the displayed standard. After deleting a record, the next record will be displayed. You may want to delete a standard if you don't want people to use it. For instance, you may want to delete the standard verb SELECTIVE SAVE so that somebody will not accidentally delete parts of a program.

NEW STANDARD

Lets you create a new standard. To abort hit <SHIFT-F10>.

You cannot really create a new standard verb or noun in PRAGMA. That is our task. This option can only restore a standard that was deleted for some reason.

LIST ALL STANDARDS

Three choices are available.

The first choice is whether to display the listing on the screen or to make a printout. The second choice asks you where you want to begin the list and the third choice asks you where you want to end it. Default lists on the screen all the records in alphabetical order.

If you wish to access the records numerically, just enter the numbers indicating where you want the list to begin and end.

To proceed to the next choice use the <TAB> key.

ACCESSING THE FILES

The following section describes how to access the PRAGMA standards file from PRAGMA.

To access the PRAGMA editor files you must have a PFM NUMERIC REFS = YES statement in your description file.

This is the file definition of PRSTD.PFM.

RECAP the definition of PRSTD

The short name is PRSTD
The Btrieve open mode is 0
The PFM unit size is 164
The mock flag is 16
The number of indexes is 3
The significant length of index 1 is 31
The significant length of index 2 is 7
The significant length of index 3 is 8

1 STD KEY NO (index selection noun)
2 STD NAME (reference, maximum length 31 characters)
3 STD ABRV (reference, maximum length 7 characters)
4 STD ID (reference, numeric)

Make sure that STD NAME never exceeds 31 bytes in length, STD ABRV 7 bytes.

Terminfo

View Topic

TERMINFO

PRAGMA uses a text file to describe the characteristics of the terminal called TERMINFO.LBS. This file MUST be available in order to run a PRAGMA program under all operating systems. There are no default values available.

TERMINFO is expected to be in the directory where PRAGMA is or, for UNIX, in the directory /usr/lib/terminfo. For DOS and OS/2 you can also create a directory called \USR\LIB\TERMINFO and put TERMINFO.LBS there. But be aware that you must create such a directory for every hard disk on your system that will run a PRAGMA program.

If you forget to install terminfo you will not be able to run any PRAGMA program but will get the following message:

"Screen Initialization error, ABORTING"

Even though it is similar in name to the UNIX terminfo package and is partially inspired by the UNIX curses package, the formats used within terminfo.lbs are totally different from and incompatible with UNIX terminfo. For a complete explanation of terminfo please ask to send you an in-depth description of TERMINFO. But we don't suggest that you start adding your own entries to terminfo.

A complete, updated list of the terminals supported by terminfo.lbs is available on request. If the description for your terminal is missing, please contact us, give us the characteristics of the terminal and we will rectify the situation.

SUPPORTED TERMINAL TYPES

The following are some of the main terminal types that are described in terminfo.lbs:

dosmem MS DOS main console writing data directly into video
memory.
dosmemmono Same as dosmem for monochrome screens.
dosansi MS DOS main console and the ANSI.SYS device driver.
dosansimono MS DOS main console and the ANSI.SYS device driver
for monochrome screens.
dosansi43 MS DOS main console with the DOS "MODE 80,43"
command to provide a 43 line by 80 column screen
dosansimono43 Same as dosansi43 for monochrome screens.

os2ansi OS/2
os2ansimono OS/2 for monochrome screens.

ansi SCO UNIX main console
ansimono SCO UNIX main console for monochrome screens

hp Hewlett Packard terminal
kt7ix Kimtron KT7 and KT70 terminal in native mode
VT100 VT100 terminal (caution made with reference to the
emulation of VT100 provided by a VISA terminal)
wy50 Wyse 50 terminal
wy150 Wyse 150 terminal

The monochrome terminal descriptions are exactly the same as their color counterparts except that the foreground and background color commands (SET FOREGROUND COLOR, SET BACKGROUND COLOR) do nothing. Setting of colors when using these terminal types is ignored.

To use terminfo you must make the following statements active:

DOS

SET TERM = DOSMEM
or
SET TERM = DOSMEMMONO (for monochrome screens)

You must put one of these statements into your AUTOEXEC.BAT file.

OS/2

SET TERM = OS2ANSI
or
SET TERM = OS2ANSIMONO (for monochrome screens)

You must put one of these statements into your CONFIG.SYS file.

SCO UNIX

TERM=ansi
or
TERM=ansimono

Installation using custom will automatically take care of setting up terminfo for your main console and will automatically choose TERM=ansi. If you wish to use ansimono instead, you have to manually change TERM in your environment. To see what is being used, type env at the operating system prompt. You will also have to select the correct terminfo for your terminals.

See also:

Environment Configuration - DOS
Environment Configuration - OS/2
Environment Configuration - UNIX

Tutorial Introduction

View Topic

UNIX - Commands

View Topic

A FEW USEFUL UNIX COMMANDS

These few commands are the ones that you will use the most to run PRAGMA under UNIX. This list is of course nowhere near complete nor does it contain the possible options. Notice that all the commands are typed in lower case letters. Also some commands can be accessed only from the superuser prompt (#).

Be very careful with certain UNIX commands. They can be very powerful and do a lot of damage without even telling you. A rm -r * will delete everything in your present directory and subdirectories without asking.

To avoid possible damages that would force you to reinstall UNIX we suggest that you experiment as much as possible as a user from the $ prompt. Be very careful when you are a superuser. If you type rm -r * in the root directory as a superuser, you will blow away the whole system. Real computer harakiry. And you will not even be asked if this is what you really want to do!

<CONTROL-D> Gets you to the login prompt.

cp Copy

chmod Change mode

custom (#) Do an installation

doscopy Copies from DOS

dosdir Lists a DOS directory

format formats a diskette on the default drive

format /dev/rfd0135ds18 formats a 1.4 MB 31/2" diskette on
what DOS would call drive A:

format /dev/rfd1135ds18 formats a 1.4 MB 31/2" diskette on
what DOS would call drive B:

haltsys (# only) Fast shutdown

l List a directory

l | more List pausing at the end of each page

man Manual (for help, if installed)

mkdir Make a directory

mv Moves files or renames them

rm Remove (delete)

rmdir Remove a directory

pwd Where am I ?

shutdown (# only) Shutdown with warning

sysadmsh (#) Where, among other things, you create a
user.

tar Tape archive. Make or restore a backup
from diskettes on the default drive.

tar tv See what is on the tar diskette.

tar cv ./* Do a relative backup of the present
directory on the default drive.

tar -cv6 ./* Do a relative backup of the present
directory on (in DOS called) drive A:
which is a type 6 drive.
Drive types for tar are found in the file
tar in the directory /etc/default/

tar -cv7 ./* Do a relative backup of the present
directory on (in DOS called) drive B:
which is a type 7 drive.

UNIX - Differences

View Topic

UNIX - Doscopy Utility

View Topic

THE UNIX UTILITY DOSCOPY

doscopy is a PRAGMA UNIX utility that lets you painlessly transfer files from DOS to SCO UNIX or vice versa without having to retype the doscp command every time for every file that you want to transfer thanks to its ability to accept wildcard characters. The SCO UNIX DOS utilities do not accept wildcard characters in filenames for the DOS names, only a filename, directory or path. doscopy will come in handy when you have to transfer PFM files from DOS to SCO UNIX and vice versa.

The file doscopy will have been automatically installed into the directory /usr/bin by the PRAGMA installation program. It has been put into that directory because that is one place automatically searched by the operating system.

Here's how you use it.

You must always use forward slashes (/) instead of backslashes (\) in all directory names because backslash is a special character in UNIX. This means you must use forward slashes in the DOS pathnames too.

Case in names is insignificant under DOS, but it is significant under UNIX. You must type a UNIX filename or pathname in the correct case. This program will always convert filenames under DOS to upper case, under UNIX they may be converted to lower case, depending on the setting of a flag.

This same program is used to copy from UNIX to DOS, or from DOS to UNIX. It can tell which way to go by looking at the two parameters given it. A DOS source filename MUST ALWAYS have a drive letter, path, and filename, with or without wildcards. A DOS destination must always have a drive, and may optionally have a path. If you have no path, it means the root. Do not put a filename on a DOS destination. The files will always have the same name in UNIX or DOS; you cannot use this program to rename a file as you can with the DOS COPY command. If you are copying to the root of the DOS disk, do not put a trailing slash (e.g., use C: instead of C:/).

If you are copying from DOS to UNIX, you must always specify a DOS filename, even if you want to copy *.*. A shortcut under DOS is that you may specify only a directory name, and this means *.*, but here you cannot do that.

If you are copying from UNIX to DOS, the UNIX path/filename must be enclosed in double quote marks. A UNIX source may have a path, but MUST always have a filename, with or without wildcards. There is no such thing as a UNIX drive. Everything is a path. The shortcut of using a directory name to mean *.* is not honored here either. A UNIX destination must always have a path, but must not have a filename.

One caution is that you must make sure there are no subdirectories in the source directory (the directory you are copying FROM), either in UNIX or DOS if you use wildcards, because this program will attempt to copy the directory file itself.

Under UNIX, the single * is equivalent to the DOS *.*, because in UNIX, *.* only matches filenames that HAVE a period in them, whereas * matches anything. This also holds true for DOS filenames, too.

There are two flags that can be used.

The first flag tells doscopy whether or not to remove/insert carriage returns. DOS, like most normal programs, uses a carriage return character AND a line feed character for the purpose of going to a new line on the printer or screen. UNIX however, uses ONLY a line feed character for this purpose, and will get upset if there is also a carriage return. Therefore, doscopy will remove carriage returns when copying text files from DOS to UNIX, and insert them when copying from UNIX to DOS. Obviously, you DO NOT want this to happen if the file is NOT a text file, like a Btrieve file. This first flag lets you turn carriage return processing on or off. If the flag is '-m', it means to turn ON carriage return processing. If the flag is '-r', it means to turn OFF carriage return processing. This means that you cannot copy both text and binary files at the same time.

The second flag is to control case conversion in the filename. If the flag is '-x', it means to convert all destination UNIX filenames to lower case. If this flag is absent, all destination UNIX filenames will be uppercase. These flags are positional; they must not be specified in the wrong order.

Note: You cannot use doscopy when logged in as ROOT (superuser). It only works when logged in as a normal user.

DOSCOPY EXAMPLES

The command line for doscopy is the following:

doscopy source destination translateflag caseflag

where translateflag and caseflag are:

-m takes out/puts in CR
-r does not take out/put in CR
-x translates the UNIX filename into lowercase letters

doscopy c:/* . -r

Copy everything from the DOS root directory of drive C to the current UNIX directory. Notice that the source DOS drive letter, path, and filename are required. The current UNIX directory is represented by the dot. The files are binary (no CR processing), and the UNIX file names will be uppercase. This is the way you would transfer PFM or Btrieve files to UNIX.

doscopy c:/work/text.* /usr/bob -m -x

Copy all files from DOS drive C, directory work, that have the filename text and have any extension, to UNIX directory /usr/bob. Note that the DOS drive, directory, and filename as always are required. This is the way you would transfer C sourcecode files from DOS to UNIX .

doscopy "*" c: -r

Copy all files from the current UNIX directory to DOS drive C root directory. Note that the UNIX source pathname is required to be in double quotes. This is the way you would transfer PFM or Btrieve files from UNIX to DOS.

doscopy "/usr/include/*" c:/include -m

Copy all files from the UNIX directory /usr/include to the DOS drive C directory include.

UNIX - Installing SCO Xenix

View Topic

INSTALLING DOS AND Xenix 2.3.1 ON A COMPUTER

The following section will help you to install SCO Xenix version 2.3.1on your computer. To have both DOS and UNIX on the same machine can be very useful if you want to do development work in both operating systems. It is not necessary to have DOS present if you only want to run a PRAGMA application under UNIX.

If you plan to compile your PRAGMA applications you should install the complete development system right from the beginning.

EQUIPMENT CONSIDERATIONS

You will need a 386 type computer with at least 2 megabytes of RAM memory (3 or more is even better) and, if you install the complete development system, at least a 60 megabyte hard disk. Be aware that Xenix is a true 386 operating system and therefore to get the maximum speed out of your system your RAM memory should be accessed by a 32 bit wide path. In other words, do not use any cheap old memory expansion card.

If your hard disk is of the standard type (MFM or whatever it is called these days), you will have no problems. If you have an RLL type, be sure to type in the hard disk parameters as non-standard, even though Xenix seems to be able to correctly see your hard disk. If your hard disk(s) is of the SCSI type, you are in for some fun. Usually the SCSI hard disk manufacturer will supply you with a device driver for that type of hard disk, since Xenix will not recognize it. The problem? In order to make a Xenix bootable diskette with SCSI you must have your Xenix first loaded on a standard hard disk. Then and only then can you create a SCSI bootable disk and install Xenix on your SCSI hard disk. A lot of work. There are no shortcuts because the bootable diskette must be made with your version of Xenix, with your own serial numbers.

We recommend that you install both DOS and Xenix on your C: hard disk in order to be able to easily switch from one operating system to the other. Take note that SCO Xenix version 2.3.1 does not see a hard disk partition larger than 32 MB created by DOS 4.01. If you choose to have a large DOS partition on your C: drive together with Xenix, you will have to use FDISK to make one or the other operating systems the bootable one. Also, to transfer files from DOS to Xenix you will have to use a floppy diskette. If you don't want to use FDISK to change from one operating system to the other, the PRAGMA diskette includes a utility called Selectboot that lets you painlessly switch from one operating system to the other when you boot your system. This utility is described in the utilities chapter of the PRAGMA manual.

The easiest way to configure your systems is to put a small DOS bootable partition on drive C and devote the rest of the hard disk to Xenix while all of the second hard disk, drive D, will be devoted to DOS. Thus, the hard disk with at least 60 megabytes should be drive C.

This configuration will allow you to switch operating system without having to use a floppy diskette to transfer files from one operating system to the other. You must put a small DOS partition on drive C because DOS cannot boot off drive D.

FORMATING YOUR HARD DISK

Before you can start installing DOS and Xenix you must make sure that you have correctly low level formatted your hard disk.

All the bad tracks MUST be marked as bad by the low level format program, which means that at low level format time you must mark all the bad spots on the disk (as listed by the drive manufacturer on the bad track list accompanying the drive). Thereafter, any program that tries to read those sections (be it DOS, Xenix or whatever) will always encounter an error, because those tracks will have been actually low level formatted as bad tracks and nothing will ever be able to read them.

When DOS or Xenix perform high level formatting and look for bad tracks, they simply write to the disk and then read it back. Sometimes a bad track is only marginal and it may pass the kind of testing done by DOS or Xenix. Then at a later date that bad track fails and you will get all kinds of weird errors.

So please low level your hard disk correctly (or have your hardware supplier do it) by marking all bad spots as bad.

INSTALLING DOS

Take your MS-DOS 4.01 INSTALL diskette and boot from the A: drive. At the first prompt press <ENTER> and follow the prompts to continue the installation.

We recommend you select the type of configuration that gives the maximum DOS function and minimum program workspace.

The installation process will take you to the Partition Fixed Disk program. Choose to define your own partition sizes.

Start with drive 1 and first display the Partition Information. It should read "No Partitions Defined", meaning that the disk is clear.

Go back to the FDISK Options menu and go to create DOS partition or logical DOS drive. In that choice type 1, create primary DOS partition.

You will be asked:

Do you wish to use the maximum available size for a Primary DOS Partition and make the partition active?

Type no, and you will be asked for the partition size in megabytes or percent of disk space (%). Since you want to make a partition from which you can transfer your PFM files, make it 31 MB.

To make this primary DOS partition active go back to the Options menu and choose option 2. You will be asked for the number of the partition that you want to make active. The active partition is the one which contains COMMAND.COM and the two hidden DOS files needed when starting the computer. Your only choice at this point is partition 1.

Exit FDISK and you will have to reboot your computer to install DOS on your C drive. Follow all the prompts and when you have finished you should have a bootable C drive.

The next step is to dedicate all your D drive to DOS. At the C prompt type FDISK. At the Options menu select drive 2. If you display the partition information for your second drive you should not have any partitions defined.

First create a primary DOS partition and use all the available size for it. Then exit FDISK and you will have to reboot your computer to activate your second drive.

After you have finished, check that upon booting that you end up on drive C and that you have access to drive D.

You now have installed all that is needed for DOS and will proceed with the installation of Xenix.
INSTALLING Xenix
Insert the Xenix boot disk N1 in your A: drive and cold boot your system. The screen will display the following information:

Xenix System V

Boot
:

Press <ENTER>. Xenix will go through a few checks and then will go into entering system maintenance mode.

You will be asked to select a keyboard. Select whatever choice pertains to your country.

Then choose 1, display current disk parameters. You will be shown the DOS partition. Quit and select 3 to create a Xenix partition. It will ask you for the starting track number of the new partition you want to create and display a table of how your disk has been partitioned so far. It should show only your existing DOS partition. In that table there will be an END number, which is the last track used by DOS. Add 9 tracks to your END number (7 are reserved for Xenix, 1 for DOS, 1 has to be left free). In our case the end track was 245, add 9, therefore the starting track number was 254. These numbers depend on the hard disk geometry and they vary from disk to disk.

Then you have to enter the partition size in tracks. In our case the total disk size was 4920 tracks, leaving 4666 tracks free (4920 minus 254). We entered that number but Xenix did not like it because it ended up writing to a reserved cylinder. It suggested starting at track 258 and assigning 4650 tracks for the total Xenix size. We deleted the wrong partition we created and entered instead the prompted numbers. Then the system seemed happy. What actually happens is that the number of tracks reserved is dependent upon the number of heads the hard disk has. Each hard disk has one reserved cylinder, which is one track of each head. A track equates with a head, in other words. In addition there is one track for the master boot loader and partition table. So the number of reserved tracks is one greater than the number of heads the drive has.

You then will have to select menu choice 4 to activate the Xenix partition.

The next menu that will come up deals with bad track management of your HD within your Xenix partition.

Do a quick non destructive scan of the entire Xenix partition when prompted, to save time. The low level format that you did before already found all the bad spots. After Xenix has done so it will show you the current bad track table and how many bad tracks were found, if any.

Quit the bad track management and enter a <CR> to use the recommended default value of space to allocate for bad tracks. Then Xenix will ask you:

Do you want to update this device with the new table? YES

Do you want to attempt to salvage any valid data on the bad tracks? NO

If you did everything right with the bad track management you will be rewarded with a "Bad tracking successful" message.

The next question is:

"Please enter the swap-space allocation."

Use the supplied default plus 500. You have to add 500 to the default because you may be installing the Development System on your machine later on. In our example Xenix suggested 2394 as a default, so we used 2894 (2394 + 500).

"Do you want a separate /u filesystem?" NO

"Do you require block-by block control over the layout of the Xenix division?" NO

We are not recreating or preserving a filesystem.

Xenix will then proceed to make the filesystem and will ask you for the serial number and activation key for the Operating System.

This will terminate your hard disk initialization procedure and you will be asked to reboot. (Don't forget to remove your floppy disk).

At boot press ENTER and you will start up Xenix.

Follow the prompts and insert all the requested diskettes.

You will be asked to assign a password for the superuser account "root". This will be the single most important password that will let you do everything. Don't forget it.

Then you will be asked a series of questions concerning the time.

"Are you in North America?" YES or NO
"Does daylight saving time (summer time) apply at your location?"
YES or NO

When you are through with this you will have terminated the installation of the minimum Xenix Run time System.

Xenix will ask you if you want to continue to install the remainder of Xenix by displaying the following prompt:

1. Operating System
2. Development System
3. Text Processing System
4. Add a Supported Product

You will want to continue the installation, therefore start by installing the Extended Operating System by typing 1.

If you decide to temporarily quit the installation you can always come back to the installation menu by typing custom at the superuser prompt (#).

Remember also that you always must exit Xenix in an orderly fashion. Don't just turn the computer off. At the superuser prompt type shutdown and wait until the system displays the message that lets you turn off the power.

Control-D is the keystroke that is vaguely equivalent to Control-C in DOS. Try it whenever you get into trouble.

EXTENDED Xenix OPERATING SYSTEM

To continue installing the extended Xenix Operating System follow the prompts and insert the required diskettes.

You will be shown a menu that asks what packages of the extended operating system you want to install. We want to install all of them, therefore at the "Install one or more packages" prompt type all .

Follow the prompts and insert all the requested diskettes.

To the question

Does this installation consist of only a root filesystem?

Answer no, since you will have subdirectories.

Then you will be asked:

Does this installation have a root File system and a user File system named "/u"?

Answer no.

You will then be asked to assign a password to login for "backup".

You will be asked to assign a password for the sysadm with super user permission. This will be the most important password, that will let you do everything.

It is important that you assign a different password for every type of login. You will be able to change these passwords if you want in the future. But you must not lose them.

To the question

Do you want to continue initializing terminfo now?

Answer yes, since you should always initialize terminfo.

Follow the prompts and insert all the requested diskettes.

Xenix will then ask you for the serial number and activation key for the Operating System.

Xenix DEVELOPMENT SYSTEM

To continue installing the Xenix Development System follow the prompts and insert the required diskettes.

You will be shown a menu that asks what packages of the Development System you want to install. We want to install all of them, therefore at the "Install one or more packages" prompt type all .

Follow the prompts and insert all the requested diskettes.

Xenix will then ask you for the serial number and activation key for the Development System.

To the question

Use TERM CAP, TERMINFO, or default, for cursor settings

It does not matter what you choose for the default curses package, but we recommend that you choose termcap curses as default. Termcap is the normal default in Xenix, and since PRAGMA does not need either of them, it is best to choose the default.

TEXT PROCESSING SYSTEM

The Text Processing System contains among other things the infamous UNIX text editor VI.

The installation is done with the custom utility.

ON-LINE MANUAL

The On-Line Manual is a great feature of Xenix and we recommend that you install it if you have it available and space on your hard disk.

The installation is done with the custom utility.

To use the manual type man at the $ prompt.

GRAPHICS INTERFACE PACKAGE

The Xenix Graphics Interface Package is not used by PRAGMA.

The installation is done with the custom utility.

UNIX - Instant UNIX

View Topic

UNIX - Printing

View Topic

FUN RINTING WITH SCO UNIX

The SCO version of UNIX does not have three printer ports as one would expect. Only two are available. The primary printer port is either called lp0 or lp1. Lp1 is only used if the parallel port is a monochrome/printer adapter card, which is unlikely. Otherwise, it is lp0. The secondary printer port is always lp2.

A simple way to find out what the heck the port is that your printer is connected to is to do this:

date > /dev/lpx where x is 0, 1, or 2

You should be able to at least get something on paper this way

Another way is to look at the bootup screen where it says what hardware is attached. You will see a line that starts with %parallel or something like that, and further along that line it will say unit=x, where x is again 0, 1, or 2.

After you find out where your printer is, you can try to get a directory on paper. All the following examples assume that your printer is attached to lp0. Do this:

l > /dev/lp0

This means to redirect the standard output of the command l to a file, or in this case, device driver, /dev/lp0.

The results will not be what you expect. What happens is that the printer prints all of the information but when it is going to a new line on the paper, it moves to the next line, but it DOES NOT do a carriage return. UNIX is a royal pain in the you-know-where about this. Some idiot decided long ago that ONLY a single line feed character is needed to mark the end of a line. This character is referred to in UNIXese as a new line character. Most other normal operating systems want BOTH a carriage return character AND a line feed character to mark end of line. And most printers do too. So we have a bit of a disagreement here. When doing l > /dev/lp0, UNIX was only sending out the new line character, without the carriage return your printer needs; so the resulting printout looks terrible.

You cannot simply send data to the printer under UNIX because all UNIX commands use only the new line character to terminate lines. You need something inbetween to insert the carriage return characters at the appropriate points. So, give up on trying to do l > /dev/lp0 and the like: it won't work.

Try the UNIX spooler, and see what happens. Run sysadmsh, and choose to add a new printer. Choose parallel port, lp0, and give it a name (or let UNIX use the default name). Then, the install program gives you a menu of printer types, and asks you to choose one. You could use a custom driver also, but more than likely it is not necessary. Keep it simple for the moment. Now, it is not a coincidence that option number two on this list of printers says a printer needing new line mapped to cr/lf' or something like that. Exactly what you are looking for!!! Choose that option without reservation.

The next question is a tricky one. It asks if this printer needs line feed, form feed and tabs to be converted. What the heck, it can't hurt anything, right ? WRONG!!! Your printer then would go into paper saving mode: everything printed would always be on the same line, and the paper would never advance. A real mess. So, answer NO to translate the line feed, form feed, and tabs. And everything will works wonderfully.

To get a directory on paper, I do this :

l | lp

Notice that you do NOT redirect the output of the l command directly to the device driver /dev/lp0 as before. That still will not work. Instead, pipe the output of the l command to the input of the lp (line printer) command. And everything from that point on is handled by lp. It spools everything, queues it up, and then prints it, preceded by a banner page.

Another way of getting a nice output that leaves a margin on the left is to type the following command:

pr -o10 filename | lp

UNIX - Running UNIX

View Topic

UNIX - Terminals

View Topic

UNIX AND TERMINALS

One of the reasons for using UNIX is that it is a multiuser system. If you want a multiuser system you must connect terminals to the machine running UNIX and now this is where the real fun starts. Mind you, connecting terminals can be as easy as plugging in the cable or it can become a frustrating experience if the appropriate terminal descriptions are missing.

Following is a short explanation for SCO UNIX which does not even scratch the surface of all there is to know about terminals, and to do so would go beyond the scope of this manual.

You can use three types of terminals for UNIX: dumb terminals, PC's running a terminal emulation program and clones of the main console that work with multiple screen controller boards plugged into the main CPU bus.

The following description will help you install a PC running a terminal emulation program and a KIMTROM KT70 dumb terminal.

BASICS

UNIX has no drivers for terminals, only for the serial ports. When you install UNIX, you will also automatically install the drivers for the standard COM ports present on your machine (COM1 and COM2). If you add additional serial ports like a Hostess board, you need to install a driver for that board. The drivers deal only with the ports, not with the terminals. A serial port driver does not know what is attached to the ports, and does not care.

Every UNIX port is identified by a name. The names are set up during the installation of the port and depend on the board used. So the first thing you must know is the name of the port that you want to use. For terminals, COM1 is always called tty1a and COM2 tty2a. But beware - these names are only valid when using the ports for terminals, NOT for modems.

Terminals are usually connected with a "null modem" cable to the ports. A null modem cable is a cable with only three wires and a shield. The three wires connect to pins 2, 3 and 7 and the wires that go to pins 2 and 3 are crossed.

KIMTRON KT70 TERMINAL

On the KIMTRON KT70 terminal you must have the following settings:

XON/XOFF enabled (XNF), RTS/CTS disabled (DTR)
IBM mode turned OFF
Hidden attributes ON
Line edit mode ON
Duplex edit mode ON
Auto NL ON
Baud rate 9600
8 data bits
1 stop bit
NO parity

The first setup menu is accessed by typing <ALT-CAPS LOCK>. Typing <ALT-CAPS LOCK> again will get you to the second setup menu and then back to the prompt. The above described baud rate, data bits, stop bits and parity are the default values used by UNIX.

PC AS TERMINAL

The advantage of using a PC under DOS as a terminal is that you can use the PC as a regular computer when it is not being used as a terminal. Theoretically any communications program will work, but more than likely you will not have a suitable terminfo for it (see more later on under TERMINAL DESCRIPTION). Also most communications programs are limited to 24 lines, and more than likely your programs will use 25 lines.

One communication program that does not have these limitations is the communications program P4TERM, especially written for PRAGMA and UNIX. It's main advantage is that many of the PRAGMA commands (particularly when using PRAGMA windows and the definition editor) are handled much faster with P4TERM than on a dumb terminal or a conventional terminal emulator program.

To install P4TERM refer to the online help entry P4TERM - Installation. Remember that the default settings for most UNIX systems to communicate with the terminals are 9600 baud, no parity, 8 data bits and 1 stop bit.

ESTABLISHING COMMUNICATION

Make sure that the null modem cable is properly connected. Start P4TERM with the appropriate parameters. If you are using a KIMTRON terminal make sure that all the settings are correct.

The following example uses COM1 on the machine running UNIX.

If the used COM1 port on the machine running UNIX has been enabled, press the <RETURN/ENTER> key a few times on the terminal, and you should get the familiar "login: " prompt.

If nothing happens, go to the console and log in as superuser (root). Enter the following command:

disable tty1a (just to make sure)

Then always as superuser, see if you can redirect output to the terminal by entering:

date > /dev/tty1a

If you see the date printed on the terminal, you are in business. If not, check the terminal, its settings, the cable, switch COM port, etc. Get that date on the screen.

When the date displays on the terminal, enable the port with the following command:

enable tty1a

You should get back the message /etc/ttys updated or something similar.

At this point, hitting <RETURN/ENTER> on the terminal, you should get the login message.

Log in, and you will get the usual greeting message.

TERMINAL DESCRIPTION

UNIX and the various programs that you will run need to know what kind of terminal is attached to this port. The system must know how to interpret the terminal's keys and how to display data on the terminal screen. Otherwise your terminal will not function properly. If you use "ansi" for the KIMTRON terminal, for instance, you will be able to access PRAGMA, but you will not be able to use the function keys.

The information on what terminal is present is provided by the UNIX operating system with the variable TERM. Since at this point the operating system does not know any better, it usually defaults to "ansi".

All programs look at the variable TERM, but the problem is that different programs use different terminal description programs. As a matter of fact, we have to deal with three description programs:

termcap (used by the Xenix login program, for instance)
terminfo.src (used by vi, for instance)
terminfo.lbs (used by PRAGMA, of course)

Since there is only one TERM variable which everybody uses, the various terminal description programs for the same terminal must be named the same. And all the three terminal programs must have a terminal description of your terminal.

Termcap and terminfo.src contain descriptions of hundreds of terminals; you will have to refer to the UNIX manuals to find the names of the described terminals.

The choice in terminfo.lbs is more limited. A complete, updated list of the terminals supported by terminfo.lbs is available on request. If the description for the terminal of your choice, with the name that you are calling it, is missing, please contact us, give us the characteristics of the terminal and we will rectify the situation.

The KIMTRON terminal is supported by all the three programs with the name "kt7ix".

P4TERM is supported with the name "p4term", but only by terminfo.lbs. You will have to add the entry p4term to terminfo.src and termcap. Please consult the entry P4TERM and UNIX for further details.

CHANGING TERMINAL TYPE

To see what TERM is active, type the following command at the UNIX prompt:

env

env stands for environment. Among other items, TERM and its parameter is displayed. To change TERM, you enter, always from the terminal whose type you are setting, the following line for the KIMTRON terminal:

TERM=kt7ix; export TERM

or for P4TERM:

TERM=p4term; export TERM

Another, more permanent way of setting the TERM environment variable is by editing the file .profile in the user's home directory.

PRAGMA FROM DUMB TERMINALS

When using the KIMTRON terminal with UNIX you will soon run into the most common problem caused by terminals. These are the subtle and not so subtle differences built into the terminals themselves. For example, what on the main console is bold text, on the KIMTRON becomes normal, and vice versa. With KIMTRON the 25th line is not supported. If your PRAGMA program makes use of the 25th line, it will be written in place of the 24th line, with not very pleasing results.

The only way to avoid this is to choose carefully terminals and make sure that they are at least as smart as the console that you use as the programming standard.

In other words, the performance and capabilities of PRAGMA on a terminal depend on how smart the terminal is and with what baud rate it has been connected to the computer running UNIX.

When working with windows, scrolling and all those niceties that work effortlessly under DOS or on the main UNIX console can become a chore when you add terminals. If you know that a program has to work on various types of dumb terminals, it is best to avoid these features and stick with a plain, and maybe a bit old-fashioned look.

As for using the PRAGMA definition editor from a dumb terminal, make sure that the PRAGMA.DES parameter EDITOR FULL SCREEN is set to YES.

See also:

P4TERM - Introduction
P4TERM- Installation
P4TERM and UNIX
Terminfo

View Topic

UNIX - VI Editor

View Topic

Upgrading to Version 4.30

View Topic

Validation

View Topic

Waiting for a Key

View Topic

What is Different from PRAGMA 3

View Topic

WHAT IS DIFFERENT FROM PRAGMA 3

STANDARD WORDS

The first big difference that is encountered when you migrate to PRAGMA 4 is that the number of standard words has dramatically increased. The reasons for this are two: first, a whole lot of verbs had to be added to fulfill certain needs such as interacting with the screen or with files in the operating system; and second, all the standard verbs have been revised to have only one possible way of being used.

ABBREVIATIONS

Abbreviations of standard words can now have a maximum of seven letters.

LENGTH

The maximum length of a standard word or a user-defined word (vocabulary name) is now 31 characters.

VERBS

All the standard words have been revised to have only one possible syntax each. Verbs having multiple syntaxes were split into two or more separate verbs.

An example is DISPLAY. One possible syntax was DISPLAY SOME NOUN. Another was DISPLAY layout 5 from SOME NOUN. The new DISPLAY command is of the first syntax only. The second syntax is handled by the new standard word DISPLAY LAYOUT. DISPLAY takes only one parameter, the value to display. DISPLAY LAYOUT takes two; the layout value, and the value to display.

In general, ALL input and output verbs (INPUT, RECEIVE, SEND, DISPLAY, PRINT, OUTPUT) have been revised in this way. Also, the file words (GET, SAVE, etc.) have all been revised in a similar manner. The two options with the file words were GET ref SOME NOUN in file SOME FILE and GET ref NEXT in file SOME FILE. In other words, a file operation with a specific reference, and a file operation with a general file reference. These general file references no longer exist as separate words in the language. There are now a lot of new standard verbs that combine the file operation and the general file reference (GET NEXT in file SOME FILE, SAVE THIS in file SOME FILE, etc.).

GO TO

When entering a GO TO statement, the label name entered is searched for. If it does not yet exist, a warning message is displayed. If RETURN is pressed, this label name will be accepted temporarily. If ESCAPE is pressed, the name may be reentered.

When exiting the definition editor and returning to START, a search is made for unresolved labels. The editor will position you at the first GO TO instruction that references each such label, and you must then correct it in some way. You cannot exit until all labels are resolved. You may have misspelled the label in the GO TO statement, or in the LABEL statement, or you may have simply forgotten a whole section of the program where the label was to be. In any event, every GO TO must have a matching LABEL in order to exit the editor.

IF and IF REFERENCE

A major enhancement has been made in the IF and IF REFERENCE commands. You now also have the ability to perform an action only when the IF or IF REFERENCE statement is found to be false. There are now three parts to an IF or IF REFERENCE statement; the IF part, the "do" part, and the "else" part. The "do" and "else" parts may also contain ANY number of lines.

If you use an IF or IF REFERENCE line while already inside the "do" or "else" part of another IF or IF REFERENCE, you then are nesting these commands. The system will keep track of this nesting to any level. To help you visualize what is happening, the system will also automatically indent all IF "do" and "else" blocks. When nesting IF's, the inner blocks will be indented multiple times, to match the nesting level. This makes for a clean looking definition on the screen, and makes it easily visible exactly what lines belong to which IF statement. You can see at a glance where each "do" and "else" block begins and ends.

When you enter an IF statement (we are referring herein to both IF and IF REFERENCE generically as IF statements), you type the verb name (IF or IF REFERENCE), the first item to be tested, the condition, and then the second item to be tested, just as with the PRAGMA 3 editor. But now, the system will go to the next line, display the "do" prompt to show you that you are inside of the "do" block for this IF statement now, and indent one level more. Each level is indented four spaces. At this point, you are in insert mode, at the beginning of what will be the very first line of the "do" block. You may of course enter now as many lines as you want, and they will ALL be performed in order when the IF statement is true, or NONE of them will be performed if the IF statement is false. You may also edit any existing line in the "do" block by pressing tab. When you have no more lines to put into the "do" block, press down arrow. This will cause the system to go to the next line, display the "else" prompt, and retain the same level of indentation (the "do" and "else" blocks are both indented to the same level). You are now in the "else" block, in insert mode, and you can add, delete, or edit lines here too, just as in the "do" block. When you are done with the "else" block, press down arrow again. The system will then go to the next line, display the "end" prompt, and unindent one level. You are now totally out of this IF statement, and are in insert mode following it. You can also tab totally through an IF, through the "do" block, into and through the "else" block. Likewise, up arrow, page up and page down will also maneuver through IF statements and their "do" and "else" blocks.

In PRAGMA 3 an IF could have one or two comparison parameters. These have been combined into a single parameter and have become a simple string. (See COMPARISON VALUES values further down).

IPC and SCREEN VERBS

All the IPC and screen utility verbs have now become standard verbs. Those utility verbs that were preceded by a dot do not have it anymore. When converting an application this change is performed automatically.

INPUT& and INPUT#

The verbs INPUT & and INPUT # have been broken out of the generic INPUT routine and been given their own names, INPUT STRING and INPUT NUMBER, respectively.

OBJECTS

Verbs may now have multiple objects. In theory, there is no limit to the number of objects. However, the input routine has been limited to accept a single digit for the number of objects. This will allow a maximum of nine.

Multiple objects are not of much use if they are called OBJECT 1, OBJECT 2, OBJECT 3, etc. That requires you to remember what they are supposed to be, or have recaps available while programming. But there is a better way. Objects can be named. You can use any allowable name for an object. These names are unique to the particular object verb in which they occur. In the definition of the object verb itself, you specify what the names of each of the objects are. These names apply only to this verb. You also can specify what prompts are given to ask for the objects when this object verb is used in another verb. Again, these prompts are separately selectable for each object verb.

This is one reason why it is nice to have the nestable definition editing ability that lets you create a new verb while in the middle of defining another verb. If the new verb is an object verb, you can select how many objects it will have, their names, and their prompts. If you want to define this verb entirely, you may, but you do not have to. Then, when you return to the original verb, the system will know what prompts to use for the objects for this new verb and how many of them there are.

You should never use the obsolete noun OBJECT or its abbreviation OB anymore, since this could become confusing. Objects no longer have abbreviations. Use the selectable object names instead.

VERB COPY

The verb VERB COPY does not exist anymore. Instead you can now copy a verb or a file by renaming it after having used the verb ALTER. See the Definition Editor section for an explanation.

NEW VERBS

For a detailed description of all the verbs, new and old, please refer to the online reference.

ASSIGN PRINTER
ASSIGN COMMUNICATIONS

These two verbs let you chose, from within a program, the printer or communications port. The optional default printer and communications assignment of the PRAGMA.DES file is overridden.

This is very handy for networks, where a station must access its own printer and the network printer. Or, you can switch from a modem to a serial printer.

CHECK SECURITY

This verb allows you to read certain areas of the security block. This lets you implement a security scheme in which your application runs only with your special security devices.

CLOSE ALL FILES

This verb releases all the records and closes all the files. A CLOSE ALL FILES is also always automatically performed when doing a SYSTEM CALL.

INPUT KEY

This verb waits for a key to be pressed and does not do anything while waiting. If no data is ready from the keyboard, INPUT KEY will stop executing until data is ready, thereby not wasting CPU time in a multiuser system.

MERGE
SELECTIVE SAVE
TRANSLATE TO C

These utilities are now standard, interactive-only verbs.

RECORD LOCKING

A completely new scheme of record locking has been implemented. You may choose between verbs that do a GET WAIT LOCK and a GET NOWAIT LOCK. You may also lock as many records you want. To UNLOCK you can choose between unlocking a record, all the records in a file or everything.

This new record locking scheme is the suggested way to go for new applications written with PRAGMA 4. If you convert an application from PRAGMA 3, the PRAGMA 3 record locking scheme is still supported.

REMOVE NAMES

This verb is similar to the operation in PRAGMA 3 that renames an application to have invisible names. Except this new verb is more comprehensive.

SAVE SCREEN IMAGE
SAVE SCREEN WINDOW TEXT
SAVE SCREEN WINDOW IMAGE

These new verbs let you put into a noun a complete or partial picture (window) of your screen. In SAVE SCREEN IMAGE and SAVE SCREEN WINDOW IMAGE all the screen attributes and colors are also saved. In SAVE SCREEN WINDOW TEXT only the text is saved.

SAVE SCREEN IMAGE comes in handy when you want to display a window and afterwards revert back to the old screen. SAVE SCREEN WINDOW TEXT lets you do bar menus or read a character off the screen.

The only restriction is that they work only with a screen that has been generated by PRAGMA. Also be aware that when saving a screen of 25 lines this screen will scroll when displayed on a monitor that supports only 24 lines.

SET FILE PATH
SET EXTERNAL FILE PATH

These two verbs let you set, from within a program, the directory where all your internal and external files reside. The optional path assignment in the PRAGMA.DES file is overridden.

They are indispensable for networks, where data files must reside on the network server. Or, simply to keep the hard disk neat and organized.

SYSTEM CALL

This lets you call another program from within a PRAGMA program. A very powerful feature.

Under UNIX the SYSTEM CALL lets you access the printer spooler, for instance. Your imagination is the limit, but don't overdo it.

NOUNS

NOUN VALUES

Noun values can be written back to the vocab at execution end. But you must enable this option in PRAGMA.DES. You also cannot share a vocab among users if you enable this feature.

NEW NOUNS

FILE STATUS

Verbs that perform file operations (external and internal) now also write the result of the file operation into the noun FILE STATUS, in addition to the noun EXTERNAL ECHO.

FILE STATUS contains a numerical value as a result, and is therefore language independent.

EXPRESSIONS

COMPARISON VALUES

In an IF statement, the comparison value is no longer a reserved word (PRAGMA 3 has actual standard words called <, >, =, and ^). It is now a simple string. For instance, an IF statement might look like this : IF FIRST NOUN ">=" SECOND NOUN do...

If the IF comparison is itself a noun, it should contain a string that is one of the allowed comparisons ("<", ">", "=", "^", "<=", ">=", "=>", "=<", "^", "><").

NULL STRING

A NULL string is a double quote followed by a RETURN. If you do a RECAP it will appear as "". The "^@", used in PRAGMA 3, is not allowed anymore.

What is New in this Version

View Topic

CustomWare^® is a registered trademark of CustomWare Designs, Inc. All rights reserved.
CustomWare^® is a registered servicemark of CustomWare Designs, Inc. All rights reserved.
All images and designs on this web site are copyrighted© 2021.
v t