VOC PQ-Type Records - PROCs |
![]() ![]() ![]() |
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.
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 environments.
Because development if 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:
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 OPTION PROC.A 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 move 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.
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.
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 identified by the file and id associated with file buffer n is deleted. 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. Multiple spaces are compressed to a single space. All spaces within the string are then replaced by field marks.
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-ref Data obtained using an A-reference ref A direct or indirect buffer reference E The value of @SYSTEM.RETURN.CODE Sn Tests whether select list is active. n defaults to 0 if omitted. The conditions are:
= 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.
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.
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 \ 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. 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. The input buffer pointer is not moved by this operation.
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{P}{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:
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.
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. 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.
|