
VISUALPQL		Buffers

Buffers

Buffers can be used to enter and edit unlimited amounts of text with minimal programming.

A program can invoke the editor which is either the SIR editor or the system editor depending on parameter settings. Once the editor is invoked , control does not return to the program until the user exits the editor. The editor can use buffers to store data and there are eight VisualPQL commands to create, read and manipulate the contents of a buffer. The commands are:

CLEAR BUFFER, CREATE BUFFER and DELETE BUFFER which affect the whole buffer.
DELETE LINE, GET LINE, INSERT LINE and PUT LINE which affect individual lines in the buffer.
EDIT BUFFER which passes control to the editor for the user to edit the buffer. Control returns to the program when the user exits the editor.

CLEAR BUFFER

CLEAR BUFFER buffer_name_exp

Removes all the lines currently in the specified buffer. Specify an existing buffer name as a string constant in quotes or as a string variable.

CREATE BUFFER

CREATE BUFFER buffer_name_exp

Creates a new, empty buffer of the specified name. Specify the buffer name as a string constant in quotes or as a string variable.

If the buffer already exists, a warning is issued but the program continues.

DELETE BUFFER

DELETE BUFFER buffer_name_exp

Removes the specified buffer. Specify the buffer name as a string constant in quotes or as a string variable. If the buffer does not exist the command is ignored and no warning is issued.

DELETE LINE IN BUFFER

DELETE LINE IN BUFFER buffer_name_exp
       NUMBERED num_value

Removes a specific line in the buffer. Subsequent lines are renumbered. Specify the buffer name as a string constant in quotes or as a string variable.

EDIT BUFFER

EDIT BUFFER buffer_name_exp

Invokes the SIR editor or the external editor with the specified buffer. Specify the buffer name as a string constant in quotes or as a string variable.

Note: There were additional parameters on this command in pre version 4 releases. If these are still on the command, they do not cause compilation errors but have no effect.

GET LINE FROM BUFFER

GET LINE FROM BUFFER buffer_name
    NUMBERED num_value
    INTO string_var

Transfers a copy of the specified line to a string variable. If the line number is greater than the number of lines in the buffer, the string is set to undefined.

INSERT LINE INTO BUFFER

INSERT LINE INTO BUFFER buffer_name
       NUMBERED num_value
       FROM string_var

Inserts a new line into the buffer before the specified line number. That is the old line with the specified line number becomes that line number+1 and the new line becomes the specified line number.

PUT LINE TO BUFFER

PUT LINE TO BUFFER buffer_name
    NUMBERED num_value
    FROM string_var

Replaces the specified line in the specified buffer with the contents of the string argument specified.

Example of Buffer Manipulation

The following example uses a bibliographic database in which abstracts of books are stored. The case identifier variable is BOOKID, a string. A record type called ABSTRACT has an integer keyfield called LINENUM and an 80 character string variable called TEXTLINE. Each line of text of the abstract is stored as a record in this record type.

The retrieval has two parts, the control structure of the program and a set of subprocedures that do the various program tasks such as looking for existing abstracts, editing the abstract and saving the abstract in the database.

RETRIEVAL UPDATE NOAUTOCASE
STRING * 80 TMPLINE
INTEGER * 2 EDITEND
CREATE BUFFER 'ABSTRACT'                | create a buffer for editing
LOOP                                    | beginning of control structure
. ERASE SCREEN                          | clear the screen
. DISPLAY TEXT 'Enter Book ID:' at 1,1  | prompt for book id
. FIELD INPUT BOOKID                    | get the book id
              at     1,16
              width 20,20
              video  4
. IFTHEN(LEN(BOOKID) = 0)               | if no bookid is provided
.  DELETE BUFFER 'ABSTRACT'            | get rid of buffer
.  EXIT RETRIEVAL                      | end the retrieval
. ELSE                                  | if we have a bookid
.  EXECUTE SUBPROCEDURE GETBOOK        | get existing abstract
.  EXECUTE SUBPROCEDURE EDITBOOK       | edit the abstract
.  IFTHEN(EDITEND = 299)               | if user cancelled
.    CLEAR BUFFER 'ABSTRACT'           | empty the buffer
.    NEXT LOOP                         | go for another book
.  ELSEIF(EDITEND = 277)               | if execute buffer
.    EXECUTE SUBPROCEDURE SAVEBOOK     | store text
.    NEXT LOOP                         | go for another book
.  END IF
. END IF
END LOOP                                | end of control structure

C** -- subprocedure definitions

SUBPROCEDURE GETBOOK                    | gets abstract from db
OLD CASE IS BOOKID
. PROCESS REC ABSTRACT
. INSERT LINE INTO BUFFER 'ABSTRACT'    | load lines into buffer
               numbered LINENUM from TEXTLINE
. END REC
END CASE
IFTHEN (SYSTEM(14) = 0)                  | if book is not in database
. BELL 1                                 | ring the bell
. DISPLAY TEXT 'New Book' at 1,38        | give a message
ENDIF
END SUBPROCEDURE

SUBPROCEDURE EDITBOOK                    | edit the abstract
EDIT BUFFER 'ABSTRACT'
END SUBPROCEDURE

SUBPROCEDURE SAVEBOOK                    | store text in database
CASE IS BOOKID                           | create or access book
SET LINENUM (0)                          | initialise line counter
LOOP                                     | go thru lines in buffer
. LINENUM = LINENUM + 1
. GET LINE FROM BUFFER 'ABSTRACT' numbered LINENUM into     TMPLINE
. IFTHEN(EXISTS(TMPLINE)=1)
.   RECORD IS ABSTRACT (LINENUM)
.   PUT VARS TEXTLINE = TMPLINE
.   END REC
. ELSEIF(EXISTS(TMPLINE)=0)            | if (end of buffer)
.   PROCESS REC ABSTRACT               | go thru any other records
             FROM (LINENUM)
.     DELETE REC                       |  and delete the record
.   END REC
.   EXIT LOOP
. END IF
END LOOP
CLEAR BUFFER 'ABSTRACT'
END CASE
END SUBPROCEDURE
END RETRIEVAL

DISPLAY WDL

DISPLAY WDL {'string_val' | varname ]

Sends either the specified string constant (in quotes) or the contents of the specified variable to the WDL (Windows Design Language) interface. This does not directly display any data to the user. The WDL script must accept this data and use it in a list or dialog.

The variable must be a string.