VOC PQ-type records - PROCs

VOC PQ-Type Records  -  PROCs

Top  Previous  Next

 

PROCs are the predecessor of paragraphs. They are generally thought to be much harder to understand and maintain but are supported in QM for compatibility with other systems. New applications should use paragraphs or QMBasic programs in place of PROCs.

 

 

1:PQ{N}  { descriptive text }
2+:PROC statements

 

 

PROCs come in two styles identified by the VOC record type; standard PROCs (PQ) and new style PROCs (PQN). QM supports the major features of PROCs but is not a full implementation of the various PROC environments found in other multivalue products.

 

Because development of new PROCs is discouraged, only an overview of what elements of PROCs are supported by QM is given here. It is not intended as a detailed reference document or a learning aid.

 

 

Proc Buffers

 

A PROC works by manipulating data in a set of buffers, each stored internally as a field mark delimited dynamic array (PQN) or a space delimited string (PQ). These are:

 

The Primary Input Buffer (PIB)

 

The PIB initially holds the command that started the PROC and any command line options. A PROC can use the PIB to store other data during its operation.

 

 

The Secondary Input Buffer (SIB)

 

The SIB is typically used to store user input entered in response to the IN statement.

 

 

The Primary Output Buffer (POB)

 

The POB is used to construct a command to be executed. Execution of the assembled command is triggered by use of the P statement or by termination of the PROC.

 

 

The Secondary Output Buffer (SOB)

 

The SOB, often called the stack, is used to hold data to be processed by the command in the POB. It can also hold supplementary commands to be executed after the POB has been executed.

 

 

At any moment, one input and one output buffer is considered as being active. The SP and SS statements can be used to make the primary or secondary input buffer active respectively. Similarly the STOFF and STON statements can be used to select the primary or secondary output buffers as active.

 

The input buffer pointer is used to identify a position within the active input buffer.

 

When a PROC starts, the primary input and output buffers are active and the input buffer pointer points to the start of the PIB.

 

 

The File Buffers

 

There are ten file buffers, numbered from 0 to 9. File buffers 1 to 9 are the standard file buffers. File buffer 0 is the fast file buffer and can be accessed with a special buffer reference syntax.

 

 

Select List Buffers

 

The eleven numbered select lists can be accessed using the select list buffers.

 

 

 

Buffer References

 

Many statements can reference buffers using the tokens shown below:

 

Token

Buffer

Direct

Indirect

%

Primary input buffer

%1

PIB field 1

%#2

PIB field referenced by #2

#

Active output buffer

#1

AOB field 1

#%1

AOB field referenced by %1

&

File buffer

&4.2

File 4, field 2

&%1.%2

File %1, field %2

&

Fast file buffer

&1

Field 1

&%2

Field referenced by %2

!

Select list

!5

List 5

!%1

List referenced by %1

 

An indirect reference uses the content of one buffer to index into another.

 

In a file buffer, field 0 references the record id associated with the buffer.

 

 

A-References

 

An A-reference is a reference to data in the active input buffer using the syntax of the A statement described in the following section. When used in this form, an A-reference does not move the input pointer or change the content of the buffers.

 

 

PROC Statement Summary

 

A        Move a field from the active input buffer to the end of the active output buffer.

 

A{c}{p}{,m}

Move up to m characters of field p to the output buffer, enclosing the text in character c.

c may be any character except a digit, left bracket or comma and defaults to a space. Specifying c as a backslash suppresses the surround character. The surround character is ignored if the data is copied to the secondary output buffer.

If p is omitted, data is copied from the field addressed by the current position of the input pointer.

If m is omitted, data is copied until the end of the field is reached.

The input pointer is positioned following the last character moved.

 

A({n}{,m})

Move up to m characters, starting at character n, to the output buffer.

If n is omitted, data is copied from the current position of the input pointer.

If m is omitted, data is copied until the end of the field is reached.

The input pointer is positioned following the last character moved.

Data copying normally terminates at the end of the field. Use the PROC.A or PICK.PROC modes of the OPTION command to enable compatibility with D3 where the copy continues past the end of the field.

 

 

B        Move the input pointer back to the previous field.

 

If the input pointer is at the start of a field, it is moved back to the start of the previous field. Otherwise it is moved back to the start of the current field.

 

 

BO        Move the output pointer back to the previous field

 

The output buffer pointer is moved back to the previous field, truncating the data at its new position.

 

 

C        Comment

 

Ctext

All text following the C is ignored.

 

 

D        Display fields from the active input buffer

 

D{ref|p}{,m}{+}

ref is a direct or indirect reference to a buffer containing the field number of the active input buffer that is to be displayed.

p is the field number of the active input buffer that is to be displayed. If p is zero, the entire input buffer is displayed.

m is the maximum number of characters to be displayed.

+        suppresses the normal newline after display

 

 

DB        Display all input and output buffers

 

The content of the primary and secondary input and output buffers is displayed.

 

 

DEBUGEnters the Proc debugger.

 

This command is supported only in QMConsole sessions on Windows or when using AccuTerm with a terminal type with a -at suffix (e.g. vt100-at). The debugger shows a portion of the Proc around the current line and the content of the PIB, POB, SIB and SOB buffers. The currently active buffers are highlighted. If the buffer content exceeds the space available to display it, the final characters shown are an ellipsis.

 

The debugger supports the following command keystrokes:

F1 or ?Show help screen
F4 or VView application screen
F5 or RRun (exit debug mode)
F8 or SStep
QQuit

 

 

DF        Display file buffer

 

DF{n}

The content of the specified file buffer is displayed. If n is omitted or specified as zero, the fast file buffer is displayed.

 

 

DS        Display select buffer

 

DSn

The content of the specified select buffer is displayed. If n is omitted, it defaults to zero.

 

 

F        Moves the input buffer pointer forward

 

The input buffer pointer is moved forward to the start of the next field. If the pointer was in the last field, it is moved to the end of the buffer.

 

F;        Perform stack based arithmetic

 

F;element{;element...}

The F; statement performs integer arithmetic using a stack. The element list contains values to be added to the stack and operators to be performed against the stack values.

refA direct or indirect reference to a buffer element to be placed on the stack.
nA numeric constant to be placed on the stack. The value may be preceded by C.
+Adds the top two stack items, replacing them by the result.
-Subtracts the top stack item from the next item, replacing them by the result.
*Multiplies the top two stack items, replacing them by the result.
/Divides the second item on the stack by the first item, replacing them by the truncated integer result.
RDivides the second item on the stack by the first item, replacing them by the remainder value.
{Interchanges the top two items on the stack.
_Interchanges the top two items on the stack.
?PMoves the top item from the stack into the primary input buffer at the input pointer position.
?refMoves the top item from the stack into the specified register location.

 

 

F-CLEAR        Clear a file buffer

 

F-C{LEAR} n

The file buffer for file n is cleared.

 

 

F-DELETE        Delete a record from an open file

 

F-D{ELETE} n

The record identified by the file and id associated with file buffer n is deleted. An error will be reported if there is no open file associated with the file buffer.

 

 

F-FREE        Release a record lock in an open file

 

F-F{REE} {n {id|ref}}

The record lock identified by the file and id associated with file buffer n is released. The record id may be specified using a buffer reference. If no id is specified or it is a null string, all locks in that file are released. An error will be reported if there is no open file associated with the file buffer.

If no file number or id are specified, all locks associated with files opened by the PROC are released.

 

 

F-OPEN        Open a file

 

F-O{PEN} n {DICT} {filename|ref}

Opens the file specified by filename or by the buffer addressed by ref, associating it with file buffer n. The DICT qualifier specifies that the dictionary portion of the file is to be opened.

If the file cannot be opened, the PROC continues at the next statement, otherwise this statement is skipped.

All files are closed on return to the command processor.

 

 

F-READ        Read a record from an open file

 

F-R{EAD} n {id|ref}

The record with id specified by id or by the direct or indirect ref is read into file buffer n. If the record cannot be found, the PROC continues at the next statement, otherwise this statement is skipped. In either case, the record id will be stored as field zero of the file buffer.

 

 

F-UREAD        Read a record from an open file with an update lock

 

F-U{READ} n {id|ref}

The record with id specified by id or by the direct or indirect ref is read into file buffer n, locking it for update. If the record cannot be found, the PROC continues at the next statement, otherwise this statement is skipped. In either case, the record id will be stored as field zero of the file buffer and the process will own the lock.

 

 

F-WRITE        Write a record to an open file

 

F-W{RITE} n

The record stored in file buffer n is written using the id stored in field zero of the file buffer.

 

 

FB        Read a record into the fast file buffer

 

FB{U}({DICT} filename|ref1 id|ref2)

The file identified by filename or ref1 is opened to the fast file buffer and the record identified by id or ref2 is read into the buffer. The U option specifies that an update lock is required.

If the file cannot be opened or the record cannot be found, the PROC continues at the next statement, otherwise this statement is skipped. Where the action fails because the file was opened but the record could not be found, the id will be stored in field zero of the file buffer and the process will own the update lock if the U option was specified.

 

 

GO        Jump to a label or a mark (Synonyms G and GOTO)

 

GO label|A-ref|ref|F|B

The PROC continues execution at the given position.

label specifies a numeric label attached to the destination.

A-ref is an A-reference used to determine the destination label.

ref is a direct or indirect buffer reference to a location containing the label.

F jumps forward to the next M statement in the PROC.

B jumps to the location of the last M statement executed within the PROC.

 

 

GOSUB        Enter a labelled subroutine

 

GOSUB label

Label specifies a numeric label at the start of the subroutine.

Execution continues at the given location. The subroutine may return to the statement following the GOSUB by use of RSUB.

 

 

H        Add text to the active output buffer

 

H{text|ref}

The literal text or the content of the buffer location identified by the direct or indirect ref is added to the active output buffer.

 

 

IF        Conditional execution

 

IF {N} condition statement

N specifies that a numeric comparison is to be performed where only the leading numeric part of the data to be tested is used.

The condition may take several alternative forms referencing an item which may be:

A-refData obtained using an A-reference
refA direct or indirect buffer reference
EThe value of @SYSTEM.RETURN.CODE
SnTests whether select list is active. n defaults to 0 if omitted.

The conditions are:

itemTests that item is not blank. Used with E, this tests whether the value is negative.
#itemTests that item is blank. Used with E, this tests whether the value is not negative.
item op text|refCompares item with unquoted literal text or a value obtained from a direct or indirect buffer reference. The operator op may be

=        Equality

#        Inequality

>        Greater than

<        Less than

]        Greater than or equal to

[        Less than or equal to

 

If text or ref is enclosed in round brackets and the operator is = or #, it is treated as a pattern match. The text item should be enclosed in single or double quotes if it contains spaces.

 

If the data identified by text or ref is multivalued and the operator is = or #, the operator tests whether item appears in the multivalued data. There are two extended syntaxes available with this style of test:

IF item = AVMBVMC GO 10VM20VM30

and

IF item = AVMBVMC GOSUB 10VMGO 20VMXDone

The first form, applicable to GO only, jumps to one of a list of labels dependant on the value of the item. The second form takes a multivalued list of statements to be executed dependant on the value of item.

The default behaviour is that the IF command compares the two items in a case sensitive manner. The PROC.IF.NO.CASE setting of the OPTION command can be used to make the comparison case insensitive.

 

 

IH        Insert test in the active input buffer

 

I{B}Htext|ref|\| \}

Copies the unquoted literal text or the data addressed by the direct or indirect buffer ref to the active input buffer at the position given by the input buffer pointer. If this is positioned at the start of a field, the entire field is replaced. If it is positioned part way though the field, the new data is appended to the portion before the input pointer position.

The input buffer pointer is not moved by this operation.

 

For compatibility with other systems, the following additional syntax elements are recognised in PQN style Procs or in PQ style Procs executed without the PICK.PROC mode of the OPTION command enabled:

The \ token with no preceding space, clears the field addressed by the input buffer pointer. If the pointer is positioned part way through a field, characters before the pointer position are retained.

The \ token with a preceding space, inserts an empty field. This syntax is not recognised as a special case if the PICK.PROC mode of the OPTION command is enabled.

Leading and trailing spaces are removed and multiple embedded are compressed to single spaces. If the B option is not present, the spaces are then converted to field marks.

 

 

 

IN        Input data from the terminal to the secondary input buffer

 

I{B}N{c}

The secondary input buffer is activated and the user input overwrites any existing content. All leading and trailing spaces in the input data are removed and multiple embedded spaces are compressed to a single space. If the B option is not present, all remaining spaces are then replaced by field marks. The optional prompt character c specifies an alternative to the default of a question mark and remains in effect for subsequent input until another prompt character is set.

 

 

IP        Input data from the terminal to any buffer

 

I{B}P{B}{c}ref

User input overwrites the location specified by the direct or indirect ref. If ref is omitted, the field addressed by the input buffer pointer in the primary input buffer is overwritten. All leading and trailing spaces in the input data are removed and multiple embedded spaces are compressed to a single space. If the B option is not present, all remaining spaces are then replaced by field marks. The optional prompt character c specifies an alternative to the default of a question mark and remains in effect for subsequent input until another prompt character is set. The prompt character must be present if ref is used.

 

In a PQ style Proc, entering a blank response retains the existing content of the input buffer. A PQN style Proc would clear the buffer.

 

 

IS        Input data from the terminal to the secondary input buffer

 

This is a synonym for IN described above.

 

 

L        Send output to a printer

 

L{'text'|ref|(col),...}{+}

Outputs the items specified in the comma separated list. These may be quoted literal text or the data addressed by the direct or indirect buffer ref. Use of ref may be followed by an input conversion code enclosed in semicolons or an output conversion code enclosed in colons.

The (col) element can be used to move to a specific column number where the leftmost column is column one.

The + element suppresses the normal newline at the end of the output.

The list may span multiple lines by breaking it after a comma.

 

 

LC        Close printer

 

The printer is closed and the output is passed to the underlying print management system for printing.

 

 

LE        Page eject

 

Starts a new page

 

 

LHDR        Set page header

 

LHDR{'text'|ref|(col)|P|T|Z|n|,...}

Sets the page header using the items specified in the comma separated list. These may be quoted literal text or the data addressed by the direct or indirect buffer ref. Use of ref may be followed by an input conversion code enclosed in semicolons or an output conversion code enclosed in colons.

The (col) element can be used to move to a specific column number where the leftmost column is column one.

The P element inserts the page number.

The T element inserts the date and time.

The Z element restarts page numbering.

The n element specifies a number of newlines.

The list may span multiple lines by breaking it after a comma.

 

 

LN        Redirect printer output to the terminal

 

Specifies that output from the L statement is to be directed to the terminal. This is mainly useful for debugging purposes.

 

 

M        Mark

 

The M statement marks a location in a PROC for use by the GO F and GO B operations.

 

 

MV        Move data from one location to another

 

MV destination source

destination is a direct or indirect reference to the buffer location to which data is to be copied.

source is a list of one or more items to be copied. Each item may be direct or indirect buffer reference or a quoted literal string.

A comma separating two items inserts the items as separate fields. Use of two or more consecutive commas with no source item between them skips fields in the destination.

An asterisk between two items concatenates them.

An asterisk after a file buffer reference as the last item in the source list copies all remaining fields from the file buffer.

An asterisk followed by a number after a file buffer reference in the source list copies the given number of fields from the file buffer.

An underscore as the last item in the list truncates the destination by removing all fields after the last one copied.

 

 

MVA        Move data from one location to another as a sorted multivalued field

 

MVA destination source

destination is a direct or indirect reference to the buffer location to which data is to be copied.

source is a direct or indirect buffer reference or an unquoted literal string.

The source data is inserted as a new value in the multivalued destination using a left aligned ascending sort order to determine its position. The item will not be inserted if it would duplicate an existing entry in the list.

 

 

MVD        Delete an entry from a multivalued field

 

MVD destination item

destination is a direct or indirect reference to the buffer location from which the data is to be deleted.

item is a direct or indirect buffer reference or an unquoted literal string.

The multivalued destination is searched for the first occurrence of item, removing this entry from the list.

 

 

O        Output text to the terminal

 

Otext{+}

The unquoted literal text is displayed on the user's terminal. The optional + token suppresses the normal newline after output.

 

 

P        Process the command in the primary output buffer

 

P{P}{H}{X}{W}{Ln}

The command in the primary output buffer is passed to the command processor for execution. Any data in the secondary output buffer is queued up as data for use by the executed command. If there is any unprocessed data remaining after the command has been executed, the first field of this data is passed to the command processor for execution, using the remaining fields as data. This cycle continues until all the data has been processed.

The P option displays the content of the output buffer before execution of the command.

The H option suppresses terminal output by the executed command.

The X option terminates the PROC after the command has been executed.

The W option displays the command and prompts the user to confirm whether it should be executed. Valid replies are Y to execute the command, N to terminate the PROC without executing the command and S to skip the command but continue execution of the PROC.

The Ln option sets process task lock n for the duration of the command.

After the command has been executed, the output buffers are cleared and the primary output buffer is activated.

There is an implied P command at the end of a PROC.

 

 

Q        Quit

 

Qtext

The PROC and all other underlying programs, paragraphs, menus, etc are terminated, displaying the optional unquoted text on the user's terminal. The user is returned to the command prompt, executing any ON.ABORT VOC entry on the way.

 

 

RI        Reset input buffers

 

RI{f|(col)

Used with no options, this statement clears both input buffers, resets the pointer to the start of the primary input buffer and makes this the active buffer.

The f option specifies that the primary input buffer is to be cleared from field f onwards, leaving the input buffer pointer positioned at the end of the remaining data.

The (col) option specifies that the primary input buffer is to be cleared from the given character position, leaving the input buffer pointer positioned at the end of the remaining data.

 

 

RO        Reset output buffers

 

Both output buffers are cleared and the primary output buffer is activated.

 

 

RSUB        Return from a GOSUB

 

RSUB{n}

Without the n option, the PROC continues execution at the statement following the last GOSUB executed.

n specifies that execution is to continue starting n lines following the GOSUB.

The RSUB statement is ignored if the PROC is not in a subroutine.

 

 

RTN        Return to a calling PROC

 

RTN{n}

The PROC returns to the PROC from which it was called, continuing execution n lines after the [] statement that called the current PROC. If n is omitted, it defaults to 1.

 

 

S        Set the input buffer pointer

 

Sf|ref|(col)

Moves the input buffer pointer of the active input buffer at the specified position.

f specifies that the pointer is to be positioned at field f.

ref is a direct or indirect buffer reference used to obtain the field number.

The (col) option sets the pointer to the given character position.

 

 

SP        Active the primary input buffer

 

The primary input buffer is activated.

 

 

SS        Active the secondary input buffer

 

The secondary input buffer is activated.

 

 

STOFF        Active the primary output buffer

 

The primary output buffer is activated. This statement can also be written as STOF or ST OFF.

 

 

STON        Active the secondary output buffer

 

The secondary output buffer is activated. This statement can also be written as ST ON.

 

 

T        Terminal output

 

Telement{,element...}

Outputs each element of a comma separated list to the terminal. The elements may be:

textQuoted literal text
refA direct or indirect buffer reference identifying the data to be displayed. This may be followed by an input conversion code enclosed in semicolons or an output conversion code enclosed in colons.
(col)Position the cursor to the specified column of the current line. The value of col may be given as a number or as a direct or indirect buffer reference.
(col,row)Position the cursor to the specified row and column. The value of row and col may be given as a number or as a direct or indirect buffer reference.
BSounds the terminal "bell".
CClears the screen.
DPauses for one second.
InDisplays character n where n may be given as a number or a buffer reference.
LTerminates a T...L loop.
SnEmits n spaces where n may be given as a number or a buffer reference.
TStarts a T...L loop where the elements enclosed in the loop will be executed three times.
UMoves the cursor up by one line.
XnDisplays character n where n may be given as a number or a buffer reference to a two digit hexadecimal value.
+Suppresses the normal newline after display.

The (col) and (col,row) elements can also be used to access the terminal control codes that use negative col values.

The list of elements for display can span multiple lines by breaking it after a comma.

 

 

TR        Enable or disable tracing

 

TR {ON|OFF}

The ON option causes the PROC processor to display each statement before it is executed.

The OFF option terminates trace mode.

The space before the mode keyword can be omitted. If no mode is specified, tracing is enabled.

 

 

U        Call a QMBasic program

 

Uname

The catalogued program identified by name is called. This program should take no arguments and can access the PROC buffers using @-variables.

 

 

U01A6        Screen painting

 

U01A6

action, action...

 

This special user exit emulation processes successive lines of the PROC as being a comma separated list of codes that control updates to the screen. Processing continues on the next line of the PROC if the final character of the current line is a comma. The codes available are:

(col,row)position cursor to specified location.
Bsound the terminal "bell".
Cclear screen.
Indisplay character with ASCII decimal value n.
Xndisplay character with ASCII hexadecimal value n.
"text"display text. The cursor is left positioned immediately following the text.

The col, row and n values may be buffer references.

 

 

U01AD        Fetch data from a file

 

U01AD

filename id fno action

 

This special user exit emulation reads four parameters from the next line of the PROC. These may be literal values or buffer references. The record identified by filename and id is read and field fno is extracted from it. The case insensitive value of action determines the destination for this data:

aappend to alternative (non-active) output buffer.
pappend to primary input buffer.
sappend to active output buffer.
tdisplay on user's terminal.
vverifies that record exists.
vaverifies that attribute fno exists.

If the successful, the next line of the PROC is skipped, otherwise it is executed.

 

 

X        Exit from the PROC

 

Xtext

Displays the optional unquoted text and terminates the PROC, returning to the calling PROC, program, menu, etc.

 

 

+        Add an integer value to a numeric field

 

+n

The specified numeric value is added to the field of the active input buffer identified by the input buffer pointer. Non-numeric data is treated as zero.

 

 

-        Subtract an integer value from a numeric field

 

-n

The specified numeric value is subtracted from the field of the active input buffer identified by the input buffer pointer. Non-numeric data is treated as zero.

 

 

( )        Transfer control to another PROC

 

({DICT} filename {id}) {label}

The PROC identified by the given filename and id is executed, starting at label, or the first statement if no label is specified. If id is omitted, the record id is obtained from the field of the active input buffer addressed by the input buffer pointer.

The buffers and pointers are not changed by this statement.

Control does not return to the current PROC when the called PROC terminates.

 

 

[ ]        Transfer control to another PROC

 

[{{DICT} filename {id}}] {label}

The PROC identified by the given filename and id is executed, starting at label, or the first statement if no label is specified. If id is omitted, the record id is obtained from the field of the active input buffer addressed by the input buffer pointer. If no filename or id are specified, transfer is controlled to the same Proc at label.

The buffers and pointers are not changed by this statement.

Control returns to the current PROC when                the called PROC executes a RTN or X statement.