VPLUS Intrinsic Calls

VOPENFORMF should be the first VPLUS intrinsic call executed in an application program. This intrinsic opens the formsfile specified in the call. Parameters passed to VOPENFORMF are the comarea array and the formsfile name. The comarea array is a 60 word communication area between the program and VPLUS. The comarea array contains assorted fields to be set before an intrinsic call.

One important field is CSTATUS or the status word. This is set on the completion of each VPLUS intrinsic call. The programmer should check this status after each intrinsic call to determine the success or failure of the call. If the status word is not zero, subsequent VPLUS intrinsic calls are not executed. If the program uses local forms storage or labeled softkeys, the FORM'STORE'SIZE and LABEL'OPTION words of the user's COMAREA must be set prior to calling VOPENFORMF. VOPENFORMF allocates additional space on the user's stack based on the values of these fields. Other words in the comarea array that need to be set prior to VOPENFORMF's call are:

In addition, for BASIC/3000 programs, USRBUFLEN should specify the number of words needed for the comarea extension on the stack.

When VOPENFORMF is executed, it opens the formsfile and allocates space on the stack for the comarea extension. The comarea extension is used by VPLUS to protect data between calls, to provide a buffering mechanism so that terminal reads are transparent to the user, and to aid in directory searches for formsfile information. Illustration 2 in the appendix of this note contains a layout of the tables which are in the comarea extension. For most programming languages, the comarea extension resides in the DL-DB area of the stack. For BASIC/3000, the comarea extension is declared as a variable of the program and resides with the global variables.

Another intrinsic which performs an open function within VPLUS is VOPENTERM. This intrinsic is called after VOPENFORMF. VOPENTERM does exactly what its name suggests. It opens the terminal as a file. In addition it sets the terminal in block mode and initializes the user function keys to contain the escape sequences which VPLUS expects.

Two parameters are passed to VOPENTERM: COMAREA and TERMFILE. COMAREA is the comarea array which VPLUS uses to communicate with the program. The words within the comarea array that VOPENTERM requires before the call are: CSTATUS, LANGUAGE, COMAREALEN and FORM'STORE'SIZE. These words were set at the time VOPENFORMF was called and therefore do not need to be reinitialized. Upon the completion of the call, VOPENTERM returns additional information (such as CSTATUS) in the comarea array which indicates the success or failure of a call. It also returns FILERRNUM which is the file system error if it could not open the terminal; FILEN which is the MPE file number of the terminal file; IDENTIFIER which contains a unique terminal ID assigned to a specific terminal; and ENVIRON which contains the logical device number of the terminal.

TERMFILE specifies a file name which is opened. This file defaults to the logical device from which the program is being run.

When debugging your VPLUS application, the messages displayed from your programs are only displayed within the unprotected fields on a form. For debugging purposes, it is possible to redirect the screen to another logical device so that an error message sent to $STDLIST is displayed in its entirety.

To redirect the VPLUS screen to another LDEV, you should:

Another method that can be used in your application is to redirect the display of the error message from the program to another device. This allows the screen to be displayed on the terminal from which you are running the program, but the error messages will be directed elsewhere. This method of redirecting $STDLIST is the easiest to use.

VGETNEXTFORM is the next intrinsic called after VOPENTERM. It is the first intrinsic to prepare and show the screen. It may also be called when a new form is to be displayed on the terminal.

The only parameter passed to VGETNEXTFORM is COMAREA. Within the comarea array, there are several variables pertinent to VGETNEXTFORM such as NFNAME, REPEATAPP, FREEXAPP and CFNAME. NFNAME is the variable containing the next form's name. CFNAME is the variable containing the current form's name. After the call to VGETNEXTFORM, the CFNAME variable in the comarea array is updated to contain the name of the form just read from the formsfile.

Upon the completion of the call to VGETNEXTFORM with $END as the NFNAME, the CFNAME becomes $END. The application must check the CFNAME to determine to shut down the application.With $HEAD, the head form which is specified in FORMSPEC, is retrieved. Within FORMSPEC, a specific form may be designated as the head form. If this field is left blank, the head form becomes the first form in the formsfile (alphabetic order of forms).When VGETNEXTFORM is called with $REFRESH, the terminal is reinitialized. If there are forms in local forms storage, the forms are cleared. Only the current form is displayed with $REFRESH, therefore prior appended screens are lost. Data, screen design, windows and softkeys are displayed again. An alternative to using $REFRESH which takes less overhead is to simply display the data again. In many cases, where the data is overlaid but the screen design is intact, this method is sufficient. An example of when this type of refresh can be used is when another user has sent a WARN message through the user's form. This refresh method would simply force data and field enhancements to be rewritten to the screen.

An example of the alternate method is:

VINITFORM (COMAREA) 
SHOWCONTROL (14:1)=1

[COBOL programmers must add 2 to SHOWCONTROL]

VSHOWFORM (COMAREA) 
SHOWCONTROL (14:1)=0

[COBOL programmers must subtract 2 from SHOWCONTROL]

Lastly, VGETNEXTFORM may be called with $RETURN. Before performing VGETNEXTFORM, REPEATAPP must be 0 as in all the above cases. VPLUS keeps track of the forms most recently used by your program. $RETURN returns the last form called. If the current form is $HEAD, it returns $HEAD again (no forms file access is actually done). The form file definition which is retrieved by VGETNEXTFORM is stored in an area of the user's stack called the comarea extension.

VINITFORM is called after VGETNEXTFORM in order to initialize any fields on a form. For example, on the field menu, the designer may specify an initial value. Or within the field processing section of the field menu, a designer may specify INIT phase specifications such as setting the field to a value of another field on the form.

VINITFORM uses any initial value specified in the FIELD MENU and performs any processing specifications defined in the INIT phase.

Any field that does not have a specified initial value is by default set to $EMPTY (all blanks). If this is a child form, the values for any fields that do not have an initial value are retrieved from the parent form. The only parameter passed to VINITFORM is COMAREA. The fields within the comarea array which VINITFORM may set are listed in the VPLUS/V Reference Manual.

Any initialized values are placed in the comarea extension's data buffer.

Before the form is displayed with the initialized fields, additional information may be retrieved from a data base, KSAM file, MPE file, or from within the program. This is application dependent. Once the data is retrieved with a DBGET or FREAD call, VPUTBUFFER transfers the data from the program's form buffer to the VPLUS data buffer. VPUTBUFFER, however, does not format the data being sent to the data buffer (e.g., strip leading zeros or format signs on numeric fields); this must be handled by the application before VPUTBUFFER is called. The comarea extension contains its own copy of the data buffer which aids VPLUS to interface with the terminal.

VPUTBUFFER is an optional step for preparing and showing the screen function. It is used if information from other sources needs to be displayed on the screen. An example is showing an employee's name which is retrieved from a personnel data base after the user has entered the employee's number.

The call to VPUTBUFFER in pseudocode looks like:

  VPUTBUFFER (COMAREA, BUFFER, BUFLEN)

There are three parameters passed to VPUTBUFFER: COMAREA, buffer, and buffer length. The COMAREA words have been set from preceding VPLUS intrinsic calls. If CSTATUS word of the user's COMAREA is not zero, the call to VPUTBUFFER does not execute. The buffer is the name of the program's form buffer whose contents are to be put to the form. The third parameter is the length of the buffer in bytes.

This intrinsic takes the current form as defined in the comarea extension form definition and displays it on the screen. A prior call to VGETNEXTFORM places the form definition in the comarea extension. VSHOWFORM displays the field values from the data buffer of the comarea extension. The content of the data buffer is affected by calls to VINITFORM, VPUTBUFFER or VREADFIELDS. VSHOWFORM also uses the global/form function keys and window buffer from the comarea extension to display the softkey labels and the window message.

The only parameter which is passed to VSHOWFORM is COMAREA. The SHOWCONTROL word in the COMAREA allows the programmer control of several VSHOWFORM options. The following paragraphs discuss some of the options and how they are used.

VREADFIELDS allows users to enter data. The read is satisfied if the user presses E or any other function key. If E is pressed, data is transferred from the screen to the data buffer in the comarea extension. Data is read in screen order, from top to bottom, and left to right.

If a function key is pressed, control is returned to the program without any data being transferred to the VPLUS data buffer in the comarea extension. Instead, the LASTKEY word in the comarea array is set. LASTKEY contains a value corresponding to the function key that satisfied the read trigger. LASTKEY will take on a value as follows:

If the HPTOUCH feature is implemented, VREADFIELDS is satisfied when a user selects a field. IN this case, no data is transferred to VPLUS's data buffer. Instead, the LASTKEY word in the comarea array is set to a negative number which indicates the field number selected. The number is negative to distinguish it from the function key's numbers which are positive 1 through 8.

The only parameter passed to VREADFIELDS is COMAREA. Within the COMAREA, the TERMOPTIONS word can be set to perform some advanced functions. These include setting up automatic reads or having a timed read.

AUTOREAD is used when VREADFIELDS is terminated by a function key instead of E. For example, if an order processing clerk is entering order information on a screen, then presses a function key labeled "MODIFY", the program needs to read the data on the screen. Without the AUTOREAD option set, the program would not read the screen. The program needs to interrogate the LASTKEY word of the COMAREA for an i value. If a non-zero value is found, it needs to proceed with enabling AUTOREAD.

AUTOREAD is enabled by setting bit 14 of the TERMOPTIONS word to 1. For COBOL programmers, ADD and SUBTRACT may be used to set bit 14. For example, in pseudocode:

   VREADFIELDS (COMAREA) 
       IF LASTKEY = 1 THEN 
       TERMOPTIONS(14:1)=1

[COBOL programmers must add 2 to TERMOPTIONS]

       VREADFIELDS(COMAREA) 
       TERMOPTIONS(14:1)=0

[COBOL programmers must subtract 2 from TERMOPTIONS]

   ENDIF

Another feature which is enabled through the TERMOPTIONS word of the comarea array is setting a timed read. The TERMOPTIONS word bit (10:1) enables a times read. Another word in the comarea array, USER'TIME, defines the time limit in seconds. Again, COBOL programmers must use the ADD and SUBTRACT to set bit 10. For example, to enable a timed read for 60 seconds in pseudocode:

   USER'TIME = 60 
   TERMOPTIONS(10:1)=1

[COBOL programmers must add 32 to TERMOPTIONS].

   VREADFIELDS(COMAREA) 
   IF COM'STATUS = 160 THEN 
   PERFORM TIME-OUT-PROCEDURE 
   ENDIF 
   TERMOPTIONS(10:1)=0

[COBOL programmers must subtract 32 from TERMOPTIONS].

This intrinsic is called to verify the data entered. If the field is defined as OPTIONAL and is left blank, no further processing is performed. To perform processing on a blank field (for instance, to set it to a value), the field type should be defined as PROCESS. VFIELDEDITS performs the following checks if the field is a REQUIRED field type or a PROCESS field type and the field contains data.

If VFIELDEDITS detects any errors on the checks listed above, the field is set in error and the NUMERRS word of the user's COMAREA is incremented by one. The only parameter passed to VFIELDEDITS is COMAREA. When the intrinsic completes, it may set the NUMERRS word within the comarea array. NUMERRS contains a count of the number of fields on the form detected in error. Note that a CSTATUS of 0 only indicates that the intrinsic executed properly, not that no errors were found; this information is contained in NUMERRS.In looking at Illustration 1, if there are any errors (NUMERRS > 0) the program calls an error processing routine. The error processing routine calls VERRMSG to retrieve the appropriate error message of the first field in error. The error processing routine then calls VPUTWINDOW which puts the error message to a window buffer maintained by VPLUS. It next calls VSHOWFORM which highlights all fields in error and displays the error message in the terminal window. VREADFIELDS is called to prompt the user to input the correct data. Then VFIELDEDITS is called once again. This loop is performed until there are no errors flagged by VFIELDEDITS.

After passing the first phase of editing, additional checks may be desired. For example, a programmatic check could be made to verify that the employee number entered exists in the company's data base. Since this type of check cannot be done in FORMSPEC, it needs to be implemented by the program with a call to a data base, KSAM or MPE file.

Before any user editing is performed, the program needs to retrieve VPLUS's data buffer into its own program buffer. A call to VGETBUFFER or VGETFIELD or VGETtype returns the data to the program's buffer. At this point, the data can be verified against a database or KSAM file or MPE file. If the programmatic edits detect an error, VSETERROR is called to set the field in error.

VSETERROR is another VPLUS intrinsic available to the programmer so that when programmatic edits detect invalid data, the field may be highlighted and set in error. The pseudocode for VSETERROR looks like:

   VSETERROR (COMAREA, FIELDNUM, MESSAGE, MSGLEN)

VSETERROR sets the field in error if it is not already in error and increments the NUMERRS word of the user's COMAREA by one. After the call to VSETERROR, NUMERRS reflects the number of fields detected in error on the form. The second parameter of VSETERROR is the field number to be set in error. The third and fourth parameters of VSETERROR are the customized error message and the error message length, respectively. If this is the first field in error, the customized error message appears in the terminal window on a call to VSHOWFORM.

In looking at Illustration 1, if the optional programmatic edits detect an error, the field is set in error by VSETERROR. The subsequent VSHOWFORM displays the programmer's custom error message and highlights the fields in error. VREADFIELDS is then called after VSHOWFORM to allow the user to input the corrected data. The data is next taken through all the passes of editing once again - beginning with VFIELDEDITS, next with the programmatic edits, and finally with VFINISHFORM.

Once the validity of data has been established with VFIELDEDITS and it has passed optional programmatic editing, VFINISHFORM can be called to perform the final totaling and editing processes. VFINISHFORM executes any processing statements defined in the FINISH phase. If there are no FINISH phase statements in the form, it is not necessary to call VFINISHFORM.

FINISH phase statements are input through FORMSPEC in the field menu at the field processing specification section. Formatting and totaling are typical functions performed in this phase. An example of the formatting at FINISH phase is right justifying a number, or stripping out a decimal point or filling a numeric field with leading zeros.

The only parameter passed to VFIELDEDITS is COMAREA. Within the comarea array, VEDITFIELDS may set the NUMERRS word. If there are any field type, data type or editing errors, the field is set in error and NUMERRS is incremented.

In looking at the flowchart, if there are any errors (NUMERRS>0), VERRMSG retrieves the appropriate error message. VPUTWINDOW puts the error message in VPLUS's window buffer. When VSHOWFORM is called, all fields in error are highlighted and the window displays the error message retrieved by VERRMSG. VREADFIELDS allows the user to input corrected data. Again, the flowchart passes through all levels of error checking from VFIELDEDITS through VFINISHFORM. Once the data passes all levels, the program proceeds to the next step.

When VREADFIELDS is performed, it returns user input data to the VPLUS data buffer. When VFIELDEDITS and VFINISHFORM are performed, the editing and formatting is performed on VPLUS's copy of the data buffer. In order to return the data to the program buffer, a call to VGETBUFFER is necessary.

The call to VGETBUFFER in pseudocode looks like:

 VGETBUFFER (COMAREA, BUFFER, BUFLEN)

The number of bytes that VGETBUFFER returns into the program form buffer is determined by BUFLEN (the third parameter of the call) and DBUFLEN (word in comarea array which contains the buffer length in bytes of the current form). DBUFLEN is set by the call to VGETNEXTFORM which retrieved the current form. VGETBUFFER transfers the lesser number of bytes between BUFLEN and DBUFLEN into the program buffer. VGETBUFFER returns all the data from the screen in a left-to-right and top-to-bottom order. Display-only fields are also returned into the program buffer and therefore you will need to ensure that the program buffer is set up to accommodate this data.

There are also two other routines that transfer data from the VPLUS data buffer into the program buffer.

VGETFIELD and VGETtype are useful to you if you want to return one field at a time to your program buffer. If the form design is changed so that fields are moved around within the form, VGETBUFFER's call requires that your program buffer matches the changes you have made to the screen. With VGETFIELD and VGETtype calls, the program buffer's definition is independent of the order in which fields are organized on the screen.

Once the data resides in the program buffer, the program may write the data to a database, KSAM or MPE file.

This takes the terminal out of block mode and resets the straps. VCLOSETERM only partially restores the terminal's configuration. One of the things that it does not do is to restore user function key labels.

If a VPLUS application terminates abnormally, VCLOSETERM is not done. Therefore, the terminal is not taken out of block mode and echo is not turned back on. Generally, a hard reset and an "e :" can reset the terminal back to a usable state.

In all languages except BASIC/3000, VCLOSEFORMF releases stack space allocated by the VOPENFORMF intrinsic. The stack space released was for the comarea extension. In BASIC/3000, since the comarea extension is declared as a global variable, the space is not released with a call to VCLOSEFORMF.

In addition, VCLOSEFORMF performs an FCLOSE on the formsfile.