|
|
|
|
|
|
|
|
HP Data Entry and Forms Management System (VPLUS) Reference Manual: HP 3000 MPE/iX Computer Systems > Chapter 6 USING VPLUS INTRINSICS
INTRINSIC DESCRIPTIONS |
|
The intrinsics on the following pages are described in alphabetic order for easy reference. However, this is not the order in which they are normally used. Table 6-7 “Intrinsics by Function Group” is provided to group the intrinsics according to the functions they perform. Note that terminal access is performed by only seven intrinsics: VOPENTERM, VCLOSETERM, VPLACECURSOR, VSHOWFORM, VREADFIELDS, VLOADFORMS, and VUNLOADFORM. The remaining intrinsics interact with the form definition, data buffer, window, and key label areas of memory. An example of the order in which the intrinsics are used is shown in Table 6-7 “Intrinsics by Function Group” Table 6-7 Intrinsics by Function Group
All intrinsics require that three items in comarea (cstatus, language and comarealen) are set before the intrinsic is called. However, two of these items, language and comarealen, only need to be initially set, prior to the first intrinsic call, since they are not modified by any subsequent intrinsics. In contrast, cstatus should be reset before calling any intrinsic after an error occurs (except for the intrinsic VERRMSG that uses cstatus in retrieving the associated error message). No running examples are provided with the intrinsic descriptions. Instead, Appendix A contains sample programs that use many of the intrinsics described in this section. Figure 6-2 Intrinsic Flow Continued:
Certain intrinsics must be called before other intrinsics can be executed. Figure 6-3 “Intrinsics Dependencies” illustrates the standard dependencies among intrinsics. For example, the terminal file must be opened before any other intrinsics are called if prompts are to be sent to the terminal. Each of the three files, terminal, forms and batch must be opened before operations can be performed on these files and before the files can be closed. Arms or disarms cursor sensing capability.
When cursor sensing is armed, the data returned after a read, as in VREADFIELDS, is prefixed with an escape sequence which contains the position of the cursor on the screen when the read terminated. This information is used by VGETSCPFIELD and VGETSCPDATA to retrieve the cursor position.When cursor sensing is disarmed, no cursor position information is available following a read. VREADFIELDS automatically disarms cursor sensing. VARMSCP should be called prior to a cursor sensing transaction to arm the cursor sensing function for the next read. This deletes any existing cursor location information. The VBLOCKREAD intrinsic reads a block of characters from a terminal in block mode. The syntax and parameter descriptions for this intrinsic are provided below.
This intrinsic reads a block of data from the terminal with a number of options. There are two major differences between VREADFIELDS and this procedure. First, it provides more options for reading data from the terminal. Second, data read is returned directly to the application buffer. There is no VPLUS form associated with the read. Like the companion intrinsic, VBLOCKWRITE, this procedure is recommended only for advanced programmers who are proficient with terminal input/output. VOPENTERM must be called before using VBLOCKREAD. The keyboard must be unlocked before calling VBLOCKREAD. (Refer to keyboard unlock options in VBLOCKWRITE.) VBLOCKREAD will lock the keyboard immediately after Enter or a function key is pressed to ensure data integrity. This procedure is primarily designed for unformatted reads. For users who do not use VREADFIELDS but use VBLOCKREAD to read data in format mode, the application data interpretation algorithm should accommodate both MDT (Modified Data Tag) and non-MDT inputs. When MDT is on, unmodified blanks and data are not transmitted from the terminal. Refer to the appropriate terminal reference manuals for further explanation of the MDT feature. The following examples illustrate a call to VBLOCKREAD using common programming languages: COBOL:
BASIC:
FORTRAN:
SPL:
Pascal:
The VBLOCKWRITE intrinsic writes a block of characters to a terminal in block mode. The syntax and parameter descriptions for this intrinsic are provided below.
This procedure writes the content of a user buffer to a terminal. TMODE options can be used to change the terminal to format or unformatted mode before the write. LOC options allow the programmer to specify the position of the screen where the write is to begin. Terminal control (TC) options can be used to control keyboard locking for the protection of data as it is being written to the terminal. TC = 1 is recommended for applications which do multiple writes to the terminal with no intervening reads. Procedures, such as VBLOCKREAD or VREADFIELDS, lock the keyboard as soon as the terminal begins transmitting data when triggered by the Enter key or a function key. VOPENTERM must be called before using this procedure. This procedure is intended only for advanced programmers who are proficient with terminal control operations and VPLUS terminal settings. Terminal keyboard operations, such as PREV PAGE and NEXT PAGE, can be performed programmatically by sending the appropriate escape sequences to the terminal via VBLOCKWRITE. VBLOCKWRITE can also be used to write large blocks of unformatted text or multiple report lines in between uses of predefined VPLUS forms. To ensure portability of the application from one driver to another, alteration of terminal straps using VBLOCKWRITE is not recommended. See VTURNON and VTURNOFF for information on how to switch between character mode and block mode without disturbing the screen.The following examples illustrate a call to VBLOCKWRITE using common programming languages: COBOL:
BASIC:
FORTRAN:
SPL:
Pascal:
Allows dynamic field attribute definition.
VCHANGEFIELD alters the run-time copy of the current form. It does not modify the contents of the forms file. The next call to VGETNEXTFORM which actually retrieves a copy of the form from the forms file will reset the field specifications. The only exception to this is when two calls to VGETNEXTFORM are performed without resetting nfname; the second call will not retrieve the form definition from the forms file. Please note that it is the responsibility of the programmer to ensure that a new data type is compatible with any initial values or processing specifications which may have been defined for the field. If the change type selected is a toggle type, (change type of 1, 2 or 3), the change specification buffer is returned with the "old" characteristics. Hence, the next VCHANGEFIELD call with the same buffer will toggle between the characteristics specified in the first VCHANGEFIELD call and the original characteristics. To toggle between two specific characteristics, VCHANGEFIELD can be used to set a field (change type of 4, 5, or 6) to certain starting characteristics without the toggle option at first. Table 6-8 Specifications Buffer
VCHANGEFIELD has no effect on the security or color enhancements; an error is returned if the codes for these enhancements (1-8 or S) are specified. VCHANGEFIELD does not alter the field error enhancement nor is this enhancement code returned when the enhancement attribute is toggled (rather the current "normal" enhancement is altered and returned if toggling).
The open batch file identified by comarea is closed when this intrinsic is called. The batch file must be closed before VCLOSEFORMF is called.
The open forms file is closed when this intrinsic is executed. Once closed, the forms file is not available for further processing.
The terminal file opened with the specified comarea is closed when this intrinsic is executed. For terminals with this feature, the local forms storage of the terminal is cleared. For additional information about about using the pseudo intrinsic .LOC to put and address into a word of the COMAREA, refer to the COBOL II/XL Reference Manual. Returns a message corresponding to the error number of an edit error or an intrinsic call error.
If an error occurs in an intrinsic call or is detected by a VPLUS edit, a call to VERRMSG returns the message associated with the error. For an intrinsic call error, cstatus is set to a nonzero value. If cstatus indicates an error, VERRMSG returns the text explaining the type and cause of the error. If VINITFORM, VFIELDEDITS, or VFINISHFORM detects a data error, cstatus is set to zero and numerrs is set to a nonzero value. If numerrs is set, VERRMSG returns a custom error message if there is one; otherwise, it returns the VPLUS error message associated with the edit error number in the VPLUS error message file. The error message, custom or VPLUS, is returned for the first field flagged in error. The message describing the error is returned to an application in the area defined by the buffer parameter. The message length can be no longer than buflen; the actual length of the message is returned in actualen. You can then call VPUTWINDOW to move this message to the window area of memory for later display at the terminal. The errfilenum contains the MPE file number of the VPLUS error message file. This file contains the error numbers and their associated messages for both intrinsic call and edit errors. It does not contain custom error messages, which are retrieved by VERRMSG through the form definition. VERRMSG opens this file if errfilenum equals zero when VERRMSG is called; it then sets errfilenum to the MPE file number of the file. The file is closed automatically when an application terminates. If the VPLUS error message file cannot be opened and read by this intrinsic, default messages are generated. If cstatus is not equal to zero, the message is:
If cstatus is zero and numerrs is greater than zero, the message is:
COBOL
BASIC
FORTRAN
SPL/PASCAL
Assume that filerrnum contains an MPE file error code. The calls to VERRMSG shown above return to your application a message describing the error and the length of this message in bytes. Edits data entered in each field of form and, if indicated, modifies data in the data buffer. If necessary, sets error flags.
This intrinsic checks the data content of each field. It checks that the data type and field type are correct, and if any special processing specifications were defined for this field in the Field Edit phase, it checks that the data conforms to these specifications. If any data formatting or data movement was specified for a field, VFIELDEDITS performs these functions on the data in the data buffer. For each field that does not pass the edit checks, VFIELDEDITS sets an error flag. These error flags are used by the VPLUS intrinsics, as shown in Table 6-9 “Actions Used by Intrinsics” In addition, these error flags can be accessed by an application with a call to VGETFORMINFO, which retrieves a table corresponding to the current error flag settings. Table 6-9 Actions Used by Intrinsics
After setting error flags for all fields with errors, VFIELDEDITS saves the error number of the first field with an error. (Fields are counted in screen order, starting at the top left and moving left to right, then top to bottom.) VFIELDEDITS sets numerrs to the total number of fields in which errors were found. If requested by a call to VERRMSG, the text associated with the error number in the VPLUS error message file, or the associated custom error message, is returned to an application. If requested by a call to VPUTWINDOW, the message is copied to the window area of memory. Then, a call to VSHOWFORM can be used to display this message on the terminal screen and enhance the fields with errors. Performs any processing specifications defined for the final phase of fields editing.
All special processing defined as part of the "finish" phase of field editing is performed by this intrinsic. Altering the next form to be displayed is a typical finish operation, and updating a save field is another. (Refer to the discussion of phases in Section 4.) Like VFIELDEDITS, VFINISHFORM sets an error flag for each field that has an error as a result of processing the form. (Refer to the VFIELDEDITS discussion.) A new VPLUS intrinsic has been added to retrieve the VPLUS ARB field mapping information. The intrinsic is named VGETARBINFO and is callable as follows:
Record VPPLUS-COMAREA << use existing definitions >>
Copies entire contents of data buffer from memory to an application.
This intrinsic transfers data from the data buffer in memory to the area in an application specified by the buffer parameter. The data includes everything in the unprotected and display-only fields on a form. Previously, data in the data buffer was stored in the order of the fields on the form, and specific fields could be moved from the buffer with VGETFIELD or VGETtype. Now, the Application-ready Buffer (ARB) allows you to specify, using the FORMSPEC ARB feature, the order in which the application should receive the fields in the buffer, and the data type conversion to be performed on each (see the discussion on creating an ARB in Section 3). You need no longer use VGETtype to convert individual fields; a call to VGETBUFFER accomplishes the task. The number of bytes moved from the data buffer is based on the number of bytes specified in the buflen parameter, or the number of bytes specified by the dbuflen item in the comarea (refer to Table 6-5), whichever is less. The dbuflen item is set by VGETNEXTFORM when the current form is read into memory. For example, if there are 20 bytes in the data buffer (dbuflen is 20), and the user requests 50 bytes in the buflen parameter, only 20 bytes are transferred. Conversely, if the user requests 10 bytes through the buflen parameter, but there are 20 bytes in the data buffer (dbuflen is 20), only 10 bytes are transferred. Designers using the ARB feature in VGETBUFFER should be aware that damaging run-time errors could occur if the application is inadvertently run on a system that has a VPLUS version earlier than B.05.00. To prevent this, the designer should do three things:
COBOL
BASIC
FORTRAN
SPL/PASCAL
The examples above transfer the contents of the data buffer in memory to an application. The current value of dbuflen is specified as the user buffer length. Copies contents of specified field from data buffer in memory to an application.
VGETFIELD transfers the contents of the field specified by fieldnum from the data buffer to a variable in an application. This is in contrast to VGETBUFFER which retrieves data according to the current field layout. When considering what is transferred by VGETFIELD, keep in mind that all the fields defined for a particular form in FORMSPEC are assigned numbers. The number assigned to a field by FORMSPEC does not change regardless of any changes to the field's position in the form or to its length and does not necessarily correspond to the screen order. The field numbers on a form can only be changed with the batch command, RENUMBER, as described in Section 7. The field number must not be confused with the field's position in the data buffer, which corresponds to its position in the form according to screen order, not assigned field number. If the number of bytes specified by buflen is less than the field size, the rightmost bytes are truncated. If the requested field has an error, its value is returned, but cstatus is set to an error number indicating the field error flag is set. Following a successful transfer, actualen contains the exact number of bytes transferred to fieldbuf, the user buffer; nextfldnum is set to the number of the next field in screen order, or to zero after the last field is processed. Note that VGETFIELD does not convert the data it moves. If you want to convert the field, you must use VGETtype, where type specifies the data type to which the field is converted. COBOL DATA DIVISION. BASIC
FORTRAN
SPL/PASCAL
Assume that the contents of field number "2" is to be copied, and that the length of this field is 12 bytes. The calls shown above copy the contents of this field into a variable in an application. Returns information about specified fields to an application.
This intrinsic accesses an internal table and places information about one or more fields into infobuf. You tell VGETFIELDINFO how many fields, how much information about each field, and the name of the form containing the fields. Table 6-10 Field Information Buffer
Keys are optional. If you do not supply a key to indicate the first field you want information about, VGETFIELDINFO starts with the first field not already reported on by the current call. As an example, suppose you want information about 10 fields, and you enter screen order numbers 3, 5, and 6 as keys. VGETFIELDINFO returns information about fields 3, 5, 6, and 7 through 13. If you enter no keys, VGETFIELDINFO returns information about fields 1 through 10. VGETFIELDINFO starts over with the first field in the form if you request information about more fields than are in the form or, if when you pass a key, your request goes beyond the end of the form. Suppose a form has 12 fields. If you request information about 10 of the fields and enter screen order number 8 as a key, VGETFIELDINFO returns information about fields 8 through 12, and then goes to the beginning of the form and returns information about fields 1 through 5. COBOL DATA DIVISION. The example shown above illustrates the data declaration of infobuf and infobuflen and the passing of parameters to VGETFIELDINFO. Note that before the intrinsic is called, infobuf is initialized to spaces (not zeros). The intrinsic copies 14 two-byte words of information about fields 2 through 6 of form FORM 1 into infobuf. Returns information about forms file to an application.
This intrinsic accesses an internal table and places information about the open forms file into infobuf. You tell VGETFILEINFO how much information you want about the file. Table 6-11 File Information Buffer
COBOL DATA DIVISION. The example shown above illustrates the data declaration of infobuf and infobuflen and the passing of parameters to VGETFILEINFO. Note that before the intrinsic is called, infobuf is initialized to spaces (not zeros). The intrinsic copies 19 two-byte words of information about the open forms file into infobuf. Returns information about specified forms to an application.
This intrinsic accesses an internal table and places information about forms into infobuf. You tell VGETFORMINFO how many forms and how much information you want about each form. Table 6-12 Form Information Buffer
Keys are optional. If you do not supply a key to indicate the first form you want information about, VGETFORMINFO starts with the first form not already reported on by the current call. As an example, suppose you want information about 3 forms, and you enter form number 6 as a key. VGETFORMINFO returns information about forms 6, 7, and 8. If you enter no keys, VGETFORMINFO returns information about forms 1 through 3. VGETFORMINFO starts over with the first form in the file if you request information about more forms than are in the file or, if when you pass a key, your request goes beyond the end of the file. Suppose a file has 10 forms. If you request information about 5 of the forms and enter form number 8 as a key, VGETFORMINFO returns information about forms 8 through 10, and then goes to the beginning of the file and returns information about forms 1 and 2. To enable applications to determine which fields are in error for a given form at run-time, VGETFORMINFO optionally returns a 32-byte bit map containing these error flags to show which fields failed the edit checks. Each field in a form is represented by a bit in the bit map according to its field creation number. The bit map is a 32-byte logical array to accommodate the maximum of 255 field numbers. The most significant (left most) bit of the first byte in the bit map array represents the field with the field number equal to 1 as assigned by FORMSPEC. For example, the field assigned a field number of 17 would be represented by the most significant bit of the third byte in the array. If a field is in error, the corresponding bit representing that field will be set to a one. Otherwise, the value will be zero. The bit map is valid for the current form only; information for the current form must be requested by form name key. If the bit map is requested for any other form, it will contain all zeros. Therefore, a value of zero should not be interpreted to mean the field is not in error for the current form, (i.e., the last form retrieved by VGETNEXTFORM). Furthermore, bit positions representing nonexistent field numbers for a given form will contain a value of zero. To retrieve the bit map, the user-supplied parameter entrylength in infobuf should contain a value of 36. This is to inform VPLUS to supply 36 two-byte words of information pertaining to the form requested. The last 16 two-byte words will contain the bit map indicating which fields are in error. The infobuflen parameter normally passed to VGETFORMINFO is calculated using the entrylength of 36. To request the bit map for the current form, the calculation is as follows:
where entrylength is equal to 36 and numofentries is equal to 1. Thus, the infobuflen parameter should contain a value of 38 when calling VGETFORMINFO. For languages which provide bit manipulation capability, the bits can be shifted left or right to determine which bits are on. For other languages, a mask may be used with the bit map to determine whether a bit is on or off. An intrinsic called BITMAPCNV is available to help decode and set bits in the bit map. Refer to Appendix I for more information. COBOL DATA DIVISION. The example shown above illustrates the data declaration of infobuf and infobuflen and the passing of parameters to VGETFORMINFO. Note that before the intrinsic is called, infobuf is initialized to spaces (not zeros). The intrinsic copies 20 two-byte words of information about 3 forms in collating sequence order, beginning with the form named FORM 1, into infobuf. Retrieves global or current form function key labels.
This intrinsic is used to copy global or current form function key labels that have been specified with FORMSPEC, VSETKEYLABEL, or VSETKEYLABELS into an application. Labels for some or for all eight function keys can be copy. The labeloption must be set to one prior to VOPENFORMF. When this intrinsic is called, any active labels are retrieved from the key label buffers in memory into an application. If there are no active labels, a buffer of spaces is returned. The labels are displayed by calling VSHOWFORM. COBOL 77 FORM-OR-GLOB PIC S9(4)COMP. Returns the native language ID assigned to the forms file. For more information on Native Language Support, see Section 8.
The forms file must be opened before calling VGETLANG. Otherwise, cstatus returns a nonzero value. The native language ID returned is always the number assigned to the forms file on the Terminal/Language Menu in FORMSPEC. If the international language ID (-1) is assigned, which means that VSETLANG may be used to specify the native language ID when the application executes, the native language ID returned by VGETLANG will be the number assigned to the forms file (-1), not the number specified with VSETLANG. Reads the next form from an open forms file into the form definition area of memory.
VGETNEXTFORM checks the value of repeatapp passed in comarea. If this value indicates the current form is to be repeated, or repeated and appended to itself, it does not read the next form, nor does it update the values of cfnumlines, nfname, repeatapp, freezapp, or dbuflen. Note that a repeating form is repeated until repeatapp is set to zero, either by an application or, for ENTRY, when the user presses NEXT FORM to request the next form, or by the FORMSPEC processing language. If the current form is not to be repeated, VGETNEXTFORM checks nfname to determine which form to read from the forms file. Copies contents of the specified save field from save field buffer in memory to an application. Syntax
Parameters
Discussion VGETSAVEFIELD transfers the contents of the save field specified by sfname to a variable in an application. If the number of bytes specified by buflen is less than the length of the save field, the right most bytes are truncated. Following a successful transfer, actualen is set to the actual number of bytes transferred to sfbuf. VGETSAVEFIELD does not convert the data moved to the application variable. Example
These calls will transfer the contents of the save field specified by SFNAME to SFBUF. If the call is successful, ACTLEN will contain the exact number of bytes transferred. Returns information about the cursor position by field number and row and column on a VPLUS screen.
When VREADFIELDS terminates, the cursor position on the screen is tracked and retrieved by VGETSCPFIELD. The information contains the field number of the field in which the cursor was positioned when the read was terminated. No cursor position information is available if a VREADFIELDS retry occurs. VGETSCPDATA returns the physical position of the cursor on the screen by row and column number. Rows are numbered from top to bottom and columns are numbered from left to right.
Like VGETSCPFIELD, VGETSCPDATA returns a -1 in fieldnum if:
VGETSCPDATA should be called after each VREADFIELDS since it first retrieves the cursor position information, then deletes the cursor position information upon procedure completion. Returns information about the cursor position by field number on a VPLUS screen.
When VREADFIELDS terminates, the cursor position on the screen is tracked and retrieved by VGETSCPFIELD. The information contains the field number of the field in which the cursor was positioned when the read was terminated. No cursor position information is available if a VREADFIELDS retry occurs. VGETSCPFIELD returns a -1 in fieldnum if:
VGETSCPFIELD should be called after each VREADFIELDS since it first retrieves the cursor position information, then deletes the cursor position information upon procedure completion. Copies character coded data contents from data buffer into an application, converting numeric value to specified type.
If there is no ARB, all data is read from the unprotected fields on the screen as character strings and concatenated to create a data buffer. The VGETBUFFER intrinsic copies the entire buffer to an application program or VGETFIELD can be used to obtain the contents of an individual field.
The VGETtype intrinsics, VGETINT, VGETDINT, VGETREAL, VGETLONG, VGETYYMMDD, VGETPACKED, and VGETZONED, have been provided to perform conversion from character coded data to the seven indicated data types. This intrinsic copies the contents of the field identified by its field number from the data buffer. (Note that this field number is a unique number assigned to each field by FORMSPEC and is totally independent of the field position in the data buffer.) The field's value must be numeric, but its data type need not be. That is, numbers in a character type field can be converted. The numeric value, stored in the buffer in character coded form, is converted to the specified type and then copied to the variable in the application. (Refer to Table 6-13 “Numeric Type Conversions” for the format of each type.) If errors occur during conversion, cstatus is set to an error code. If the requested field has an error, its value is moved to the variable, but cstatus is set to an error code. The default behavior for VGETPACKED and VGETZONED is to produce an unsigned result. If a signed result is desired, the negative of the number of digits in the receiving variable should be passed in the "numdigits" variable. For example, if the number of digits in the receiving variables is 6, and a signed result is desired, then -6 should be placed in "numdigits". Table 6-13 Numeric Type Conversions
The following chart will help you correlate VPLUS data types with VGETtype intrinsics and programming language data types. Table 6-14 Correlation of VGETtype with the Data Types for each Language
COBOL 77 FIELD-NUM PIC S9(4)COMP. BASIC 210 F1=5 FORTRAN FIELD=5 SPL/PASCAL INTEGER The calls in this example convert a value contained in field 5 in the data buffer to two-byte integer representation and store it in an application. Converts data in the data buffer to a eight-byte character value and copies it to an application. Syntax
Parameters
Discussion VGETYYYYMMDD transfers the contents of the field specified by fieldnum to a variable in an application. The contents of the field are stored in a data buffer from which the value is taken. This value is converted to YYYYMMDD format and the converted value is placed in the application variable. The YYYYMMDD format is an 8-byte ASCII value, for example, 19961225. If errors occur during conversion, cstatus is set to an error code. If the requested field has an error, its value is moved to the variable but cstatus is set to an error code. Refer to the VGETtype intrinsic description in the Data Entry and Forms Management System VPLUS Reference Manual for related information. Example
These calls will convert the contents of the data buffer corresponding to the field specified by FIELDNUM and place the converted value into VARIABLE. Initializes fields in data buffer according to specifications defined in the initialize phase of field definition. Both VOPENFORMF and VGETNEXTFORM must have been executed successfully prior to calling VINITFORM.
Certain values may be assigned to fields as initial values. These values are determined by special processing specifications that are explicitly or implicitly defined as part of the initialize phase of field processing using FORMSPEC. These values include any initial values specified on the Field Menus for the form. If no initial values were specified, all fields are initialized to blanks by VINITFORM. If the form being initialized is a child or sibling to the previous form, data from the previous form is transferred to this form (with conversion if necessary) before initializations occur. If a field in a child or sibling form must be initialized to blanks, use $EMPTY as an initial value. VINITFORM only resets the field error flag if the field is initialized explicitly by initialization phase (INIT) processing specifications. Loads specified forms into terminal local form storage memory.
This intrinsic is used on terminals having local form storage. VLOADFORMS loads the forms named in forms into terminal local form storage memory in the order they are specified. It may not be possible to load all the forms named because of a limit of available space in local form storage or in the form storage directory (set with formstoresize prior to VOPENTERM and VOPENFORMF). When there is no more space, any other forms named in forms are ignored. The value returned in the formsloaded parameter is:
where formsadded is the number of forms specified in the forms parameter that were actually loaded into the local storage of the terminal and formsalreadypresent is the number of forms specified in the forms parameter that were confirmed to already exist in the local storage. Because forms are loaded by form name, family relationships are ignored. Multiple family members can be loaded at the same time. Note that the terminal keyboard may be locked briefly while VLOADFORMS verifies whether or not a form was loaded. In case keys are pressed during this time, the terminal beeps to indicate that the keystrokes and/or entered data are lost. You can avoid this by not calling VLOADFORMS between calls to VSHOWFORM and VREADFIELDS. Refer to the discussion on "Local Forms Storage" earlier in this section. COBOL 77 NUM-OF-FORMS PIC S9(4)COMP. BASIC 10 INTEGER N,F FORTRAN INTEGER*2 NFORM,FLOAD SPL/PASCAL INTEGER VMERGE is a new VPlus utility that allows you to combine two or more separately-compiled VPlus forms files into a single forms file, which may then be used with an application program to manage the entry and/or retrieval of data. Combining multiple forms files with VMERGE provides the following advantages:
VMERGE usually resides in PUB.SYS. It may be run on either MPE/iX or MPE V. Before VMERGE is invoked, you must specify two input forms files and one output file. The input files are specified with file equations for the formal designators VMASTER and VAUX. The output file is specified with a file equation for the formal designator VOUTPUT. VMASTER and VAUX must exist, and each may be of type VFORM (slow forms file) or VFAST (fast forms file). VOUTPUT is created by the VMERGE utility and is of type VFAST. As VMERGE runs, informative messages are presented on $STDLIST. If any problems are encountered, appropriate error messages are displayed. These message are described in the "VMERGE Messages" section in this article. VPlus forms files exist in files with two different file codes: VFORM (slow forms file) and VFAST (fast forms file). VFORM files are created and modified with FORMSPEC. VFORM files contain the "source" for each form in the file, coded in a way that FORMSPEC can understand. When a forms file is compiled by FORMSPEC, "object" forms are added to the VFORM file. The object forms are accessed when the forms file is used with ENTRY or another application program that invokes the VPlus intrinsic functions. When you use FORMSPEC to compile a VFORM file, you may request the creation of a fast forms file. This file contains only the object forms for the forms in the specified VFORM file. Processing the VFAST file is fast because the file is smaller than its corresponding VFORM file. That is, the fast forms file does not contain source forms and, therefore, can be accessed faster. Since a fast forms file does not contain source forms, it cannot be modified by FORMSPEC. Both VFORM and VFAST files are limited in the number of records they can hold. However, the problem is more severe with VFORM files since they contain both source and object forms. Previously, the only way to create a fast forms file was by compiling a VFORM file with FORMSPEC. Consequently, you might have been unable to include forms that theoretically could have fit into a VFAST file, since the source and object forms might have been too large to fit into a VFORM file. Now, VMERGE gives you an alternate method for generating VFAST files that contain additional forms. However, VFAST files still have limited capacity, and so there are still limits on the total number of forms you can place in a forms file, even using VMERGE. Initial analysis shows that the ratio of fast form file size to slow form file size is around 1/3 to 1/10. This suggests that you can expect to combine forms from three or more nearly full (to FORMSPEC) forms files into one forms file, by using VMERGE. However, this is an estimate only, since non-typical forms files may vary considerably in their object to source ratios. Not all forms files can be successfully combined using VMERGE. The input forms files must be "compatible" in order to be combined with VMERGE. The compatibility factors are:
There are a number of forms file characteristics that may differ between the two input files that are not serious enough for VMERGE to consider the two files as incompatible. These include: head form name, error enhancement, window display line, error window color, and window enhancement. The characteristic found in the VMASTER file is retained in the VOUTPUT file. VMERGE takes two FORMSPEC-compiled forms files specified by the VMASTER and VAUX file designators, extracts the object forms from each file, and places these forms in a VFAST file specified by the VOUTPUT file designator. Every forms file has a $HEAD form designated for it. Additionally, every form in a forms file has a "Next Form" designated for it. Next Form may be $HEAD or it may be the name of another form in the file. In order to compile a forms file, FORMSPEC requires that any form named as the $HEAD or as a Next Form exist in the file. Consequently, it is impossible for a form in the VMASTER forms file to refer to a form in the VAUX forms file as its Next Form and vice versa. Therefore, the application program used with a combined forms file must be coded to sequence among the forms in the combined forms file without depending on the Next Form designation. The Next Form designation can only be used when it and the current form originated from the same forms file. VMERGE users should be aware that VMERGE makes the $HEAD form from VMASTER the $HEAD for VOUTPUT. If data entry operators are used to seeing the $HEAD form from the VAUX file, they may be surprised if this $HEAD form is no longer what is displayed when they bring up their application. VMERGE normally resides in PUB.SYS; if it is moved from PUB.SYS, it must be moved to a group with "DS" capability. VMERGE is invoked with the following command:
Before invoking VMERGE, three file equations must be given. The two VMERGE input forms files are indicated by the file designators VMASTER and VAUX. VMASTER and VAUX must designate existing forms file, with file codes VFORM or VFAST. The VMASTER and VAUX files must have been compiled with a recent version of FORMSPEC. If an input file is provided that does not meet this criterion, a message is given, and VMERGE processing halts. VMERGE's output VFAST forms files is indicated by the file designator VOUTPUT. If the designated file already exists and has the file code VFAST, then it is purged and recreated by VMERGE. If the file exists but has a file code other than VFAST, the file is not purged, a warning message is given, and VMERGE halts. The files used by VMERGE are opened for exclusive use to avoid concurrent update problems. Two JCWs (job control words) are defined for use with VMERGE: VMERGETERSE and VMERGEERROR. If the user sets VMERGETERSE to 1 before running VMERGE, then the messages indicating the form names contained in the VMASTER and VAUX files are suppressed. The VMERGEERROR JCW is set by VMERGE after it runs. If VMERGE detected a severe error that prevented the VOUTPUT file from being successfully created, VMERGEERROR is set to 1. If VMERGE successfully created the VOUTPUT file, VMERGEERROR is set to 0. Suppose your company has three distinct uses for an order form prepared by a salesperson. The order form is used in the shipping department, the billing department, and the marketing department. Currently the original order form is passed among three clerks who each enter their data using their own VPlus forms files (SHIPFF, BILLFF, and MARKETFF) that are distinct to their respective departments. Your job is to merge the forms files and fix the application program so that one clerk can enter the data for all three departments. You decide that each of the three application areas (shipping, billing, and marketing) should be selectable by pressing a function key. Once an area has been selected, processing will be performed using the same sequence as when the application for that area existed on its own. Remember that while combining the three applications into one, you will need to examine the effect of $HEAD being different from what two of the original three programs expected. Most likely, you will want to create a new form to serve as the $HEAD for the combined application. After examining and fixing the application program, you will need to look at the forms files and make them compatible, if they are not already. You will need to make sure that the save fields, if any, have distinct names and are identical in each of the forms files that uses them. Additionally, you will need to check that the global function key specifications are compatible in the three forms files. Note that in some cases incompatibilities may be so extensive that it will be impossible to merge the forms files. Next you determine what order to merge the forms files together. Suppose in this example that the marketing forms file is much more volatile than the other two. Therefore, you decide that this file should be the last one merged. You also need to decide which form your combined application should use as its $HEAD. Suppose in this example you depend on the $HEAD form from BILLFF being the $HEAD of the combined forms file. Combining the forms files is accomplished in two stages. In the first stage you enter:
VMERGE creates the intermediate forms file INTERFF. In the second stage you enter:
VMERGE creates the final forms file COMBOFF. You may wish to keep the intermediate forms file, INTERFF, so you won't need to recreate it if only MARKETFF changes. Now you could test COMBOFF with your combined application program. Another use of VMERGE is to divide an existing forms file into two or more smaller forms files. This might be desirable if different forms in the original forms file were going to be modified by different people, or if compiling the entire forms file takes a long time. When VMERGE is used to divide a file, there are few compatibility problems since the original form file is already "merged". You will have to be careful not to introduce incompatibilities (for example, refer to the $HEAD and Next Form issues discussed earlier) as a result of dividing the file. Suppose you want to remove forms F1, F2, and F3 from a forms file named BIGFF and place them into another forms file, LITTLEFF. The F1, F2, and F3 forms are changed often, and you want to separate them out in order to minimize the time it takes to recompile each time changes are made. First, you would FCOPY BIGFF to LITTLEFF by entering the following command:
Second, you would run FORMSPEC on BIGFF to delete forms F1, F2, and F3. You would need to correct the Next Form fields for any affected forms. Third, you would probably want to take advantage of some of FORMSPEC's batch mode facilities to delete all but the F1, F2, and F3 forms from LITTLEFF (see the Deleting Forms Using FORMSPEC's Batch Mode Facilities section below). Fourth, you would compile both forms file to verify that no $HEAD or Next Form dependencies exist. The compilation for BIGFF will be lengthy, but it will only need to be done once. Fifth, you would make your changes to the forms in LITTLEFF and add additional forms that could not be put into BIGFF due to size limitations. After you had taken all these steps you could combine the two forms files with VMERGE:
Check your application using the SUPERFF forms file. Opens existing batch file for processing; or, if the specified file is new, creates a batch file and then opens it for processing.
VOPENBATCH opens the specified batch file for processing by the calling program. The batch file may be an existing file or a new file. If the named file already exists, VOPENBATCH initializes recnum to the record number of the next record in the file, and numrecs to the total number of existing batch records. Thus, a user resuming collection does not overwrite data collected into previous batch records. VOPENBATCH sets nfname to the name of the form associated with the batch record to be collected. This record is identified by recnum. VOPENBATCH keeps track of forms sequence in order to associate a form with a record. For example, if a batch file is closed after record 6 of FORMA was collected, and FORMA is a repeating form, the batch file starts with record 7 FORMA when it is next opened by VOPENBATCH. VOPENBATCH also resets the global environment (save fields and so forth) to the environment existing when collection stopped. (All this information is derived from the file labels preceding each file.) If the named file does not exist, VOPENBATCH creates a new file with the specified name and sets recnum and numrecs to zero. A new batch file created by VOPENBATCH has the following characteristics:
The size of the fixed-length batch file records must be large enough to hold the largest data buffer used by the forms file associated with the batch file, plus 10 two-byte words for batch record control information. If the largest data buffer is an even number of bytes, an additional two-byte word is added before the control information. This batch record information consists of:
Total = 20 bytes The above batch record information is written at the end of each record in the batch file, starting on a two-byte word boundary. To illustrate, assume the record size is 74 bytes, and the data only requires 35 bytes (bytes are numbered from 1):
In addition, VOPENBATCH creates sufficient user labels (each 256 bytes long) to hold any save field buffers, plus 176 bytes for the collection environment and the forms file version. The length of the save field buffers depends on how many (if any) save fields were defined for the form and the length of each. The collection environment consists of the forms file name and version number, the next form name, and 122 bytes of system information. This information is stored as follows:
For example, assume that the save fields buffer requires 242 bytes. The following user labels are created by VOPENBATCH: LABEL 0 — Contains first 80 bytes of Save Fields buffer
LABEL 1 — Contains remaining 162 bytes of Save Fields buffer
Note that the length of the save fields buffers is determined by taking the number of bytes in each save field, summing them together, adding one byte, and then, if odd, rounding the total up to an even number. Should you want to create your own batch file rather than calling VOPENBATCH, you must build the file using the above record format and user label requirements. Also, if you create a batch file with variable-length or undefined-length records rather than fixed-length records, browsing of the batch file is not allowed. Undefined-length records are formatted like fixed-length records. If you do, nevertheless, want to create a batch file with variable-length records for data collection only, the batch file information is stored immediately following the data in each record. Assume a variable-length record with 35 bytes of data:
The total size of this record is 56 bytes. Depending on the size of the data, other records have varying lengths. The maximum size of the variable-length records must be the size of the largest data buffer (in bytes) plus 20 bytes for the batch record information. COBOL
BASIC
FORTRAN
SL/PASCAL
If the requested batch file name is an existing file, it is opened and the user can continue to enter data into the record following the last record that contains data. If the requested batch file name is a new file, VOPENBATCH creates a batch file and data entered at the terminal is written to the first record in the file (record 0).
VOPENFORMF opens the specified forms file for processing by the calling application. If the calling application is BASIC, it must provide its own comarea extension immediately following the comarea and specify the size of this extension in usrbuflen. If the application is written in a programming language other than BASIC, a DL area is obtained for use as the comarea extension. In this case, the application must not use the DL area for other functions. Refer to Appendix E for more information on the DL area. The forms file listing gives an estimate of DL to DB area used. You use this estimate with the MAXDATA parameter at PREP or RUN time. The labeloption must be set to one if you are using function key labels. Opens a VPLUS supported terminal.
This intrinsic opens the terminal as a file. If you are running your program as a session with your terminal as the open terminal file, the terminal name should be left blank so that the session device is opened. If you are opening a form, you should call VOPENFORMF before using this intrinsic, Once the terminal is opened for control by VPLUS, an application should not call system intrinsics to communicate with the terminal. All terminal I/O must be controlled through VPLUS intrinsics. If you are using an HP 2640B or HP 2644 terminal and the terminal is not in block mode, VOPENTERM asks you to press the BLOCK MODE key; other terminals are set to block mode automatically. The data capture devices are treated as character mode terminals. COBOL 77 T1 PIC X(8) VALUE "VTERM This example opens the device referenced by the file equation VTERM. If no file equation exists, the default is the logon device. BASIC
FORTRAN
SPL/PASCAL
The examples shown above open the session device with comarea identified as COMAREA (C(60) for BASIC). Allows an application to position the cursor to any input field at run-time.
VPLACECURSOR allows an application to position the cursor to any input field at run-time. This intrinsic places the cursor to the input field specified by fieldnum. Calling VPLACECURSOR with a positive number indicates the field number; a negative number indicates the screen order number. Using the field number is preferable because if the fields in a form are rearranged, no modification to an application is necessary. VPLACECURSOR must be called after calling VSHOWFORM. VPLACECURSOR returns an error if the field number or the screen order number does not exist. An error is also returned if the intrinsic is called to place the cursor to a display-only field. Protects a user-specified portion of the batch file data from a system crash by posting an end-of-file mark after the last record referenced and updating the batch file labels.
VPOSTBATCH posts an end-of-file mark after the last record referenced in the batch file and updates the environmental information found in the file label. Refer to the discussion of VOPENBATCH for a description of the environmental information. If a system crash or power failure occurs while the batch file is open, all data before the end-of-file mark is preserved, and data collection continues from that point. In ENTRY, VPOSTBATCH is called after every 20 records, though you may extend or shorten this posting interval. Two cautions:
Prints the current form on an off-line list device.
VPRINTFORM prints the current form to a list file. It is analogous to VSHOWFORM, in that it prints the form and the current data buffer values, except that VPRINTFORM prints the form on a hardcopy device rather than on the terminal. Enhancements obviously cannot be shown directly; the window line and key labels are not printed. The form must have been read into the form definition area of memory by a prior call to VGETNEXTFORM. The information printed depends on what is in the data buffer, which may not necessarily be the same as what is displayed. The carriage control character specified in the pagecntl parameter is effective after the form is printed. If the calling program opens the list file, it must supply the file number of this file in printfilnum. If printfilnum is zero, VPRINTFORM opens a list file and sets printfilnum to the file number of the file. VPRINTFORM opens the list file, with the formal and actual file designator FORMLIST, assigns it to the device class LP, and specifies its length as 80 bytes. This is equivalent to using the file equation:
A user may change any of these characteristics with an MPE :FILE command. COBOL
BASIC
FORTRAN
SPL/PASCAL
Each of the calls shown above prints the current form on a list device; if not already open, it opens the device file. Prints the entire contents of a terminal screen to an off-line list device or laser printer during VPLUS execution.
This intrinsic provides the capability for printing the current screen display with function keys, line drawing characters and appended forms, as well as the data on the screen. It differs from VPRINTFORM, which is limited to printing only the data in the form data buffer. However, VPRINTFORM offers the option of underlining fields, which VPRINTSCREEN in LP mode does not. The programmer can produce copies of VPLUS screens in either of two ways: incorporating VPRINTSCREEN into an application so that screen images can be captured at run-time with their data, or developing a simple utility that allows data to be entered into the screens before calling VPRINTSCREEN to reproduce them. The utility has the advantage of removing the overhead caused by VPRINTSCREEN from the application, while still providing a way to reproduce screens and data for product literature. VPRINTSCREEN always uses the Pascal HEAP procedures to perform stack allocation. This introduces the risk of conflict for programs written in COBOL, FORTRAN/66 or SPL, because the existing intrinsics would use DLSIZE for stack allocation in these cases. Applications written in these languages must, therefore, follow two rules when calling VPRINTSCREEN. They are:
Refer to Appendix E of this manual, and to the COBOL and Pascal reference manuals, for more information on calling mechanisms. For applications that use a language id of 5 in the VPLUS comarea, including Pascal, FORTRAN/77 and HPBUSINESS BASIC, VPLUS uses the HEAP procedures for stack allocation, so VPRINTSCREEN can be called in the standard format. The programmer may implement this feature by defining a function key that allows the user to print the screen contents at any time. This would be useful for providing immediate output during production. VPRINTSCREEN operates in two modes, normal and documentation mode. A VPLUS supported terminal is required for execution of this intrinsic. This is the default calling mode for VPRINTSCREEN. When called, the value in the printnumfile word of the comarea is used to determine the list device. If the calling program opens the list file, it must supply the file number of this file in printfilenum VPRINTSCREEN opens the list file with the formal and actual file designator FORMLIST, assigns it to the device class LP, and specifies its length as 80 characters. This is equivalent to using the file equation:
The user may change any of these characteristics with a :FILE command.
Each time VPRINTSCREEN is called, a PAGE EJECT is performed at the end of the print operation. You require TDP in order to use VPRINTSCREEN in this mode. VPRINTSCREEN, in conjunction with TDP, provides the capability to print screen contents on a laser printer (HP2680A or HP2688A). In this mode, field highlighting other than color, borders, alternate character sets and active function keys are captured and converted to the requisite font for printing on the laser printer. Documentation mode is enabled by setting a JCW before running the program. It is:
When VPRINTJCW is set to 1, the list file FORMLIST is NOT opened. Instead, a temporary file called EPOCLIST is created (or appended to, if it already exists). EPOCLIST can be saved and renamed on completion of the screen capture, then input to TDP and 'finaled'. The user can add text to the file or include it in a separate TDP file. Refer to the TDP Reference Manual for more information on use and include files. The following files are sample files supplied on the FOS installation tape. They should be restored to a local group to be used by applications using VPRINTSCREEN in documentation mode. To accomplish this, mount the FOS tape and perform the following restore commands:
These files may also be a non-local group, provided the application supplies a file equation, T. E.,
In order to print the forms on a laser printer, an environment file must be created (if it does not already exist). Refer to the IFS/3000 Reference Guide for more information. The environment files for the HP2680 and HP2688 laser printers are VENV80 and VENV88 respectively. All environment files must include the font ids listed under "Limitations" below. EPOCLIST uses VSETUP, a TDP include file, as the default file to reference the environment files, which must be accessible to TDP in order for EPOCLIST to be printed. If an environment file other than VENV80 or VENV88 is used, EPOCLIST must be modified to reference this file, and the font definitions from VENV80 and VENV88 must be included in it (see "Limitations" below). Printing Screens from TDP. To print the contents of EPOCLIST to a laser printer, follow these steps:
The screens will be printed out, one per page. Step 8 and 9 may be specified in a job stream. Merging Screens with a TDP File. You can include screens in an existing TDP document easily by using the file VEPOCUSE, a TDP use file that divides EPOCLIST into separate files containing one screen per file. The VSETUP file must be included as one of the first statements of the TDP document so that the correct environment file is referenced for printing the screens. Follow these steps:
It is recommended that screen files be included as separate, individual files in a document, rather than being incorporated directly into the text, because EPOCLIST has a record size of 168 bytes and most document files are set to 80 bytes. These files may also be a non-local group, provided the application supplies a file equation, T. E.,
The following limitations pertain to the use of VPRINTSCREEN.
Copies data from an application to the data buffer in memory.
This intrinsic transfers data from a buffer in an application to the data buffer in memory. The length of the data moved is based on the number of bytes specified in the buflen parameter and the number of bytes in the largest data buffer in the forms file, whichever is less. The length of the buffer assigned to the current form is not considered since the user may intend the data for another form with a longer buffer length. For example, assume there are three forms in the forms file:
In this case, the maximum data buffer length is 200 bytes. If the current form is form A and the user calls VPUTBUFFER with a user buffer length (buflen parameter) of 200, he may intend to call VGETNEXTFORM to get form B and then VSHOWFORM to display form B with the 200 bytes of data moved to the data buffer with VPUTBUFFER. Fewer bytes than the data buffer can hold may be transferred; the remaining space in the data buffer is not changed. The data moved to the data buffer is exactly as it appears in the application buffer. (If you want the data converted to USASCII in the data buffer, you must use VPUTtype, where type is the data type of the field in an application.) When the data is displayed, it is moved to each field in the form in sequence from left to right, top to bottom. If any field being replaced by user data contained an error, VPUTBUFFER clears the error flag for the field and decrements numerrs. Designers using the ARB feature in VPUTBUFFER should be aware that damaging run-time errors could occur if the application is inadvertently run on a system that has a VPLUS version earlier than B.05.00. To prevent this, the designer should do three things:
COBOL 01 DAT1. BASIC 235 L1=24 FORTRAN CALL VPUTBUFFER(COMAREA,DAT1,DBLEN) SPL/PASCAL BYTE ARRAY DAT1(0:23); The following calls transfer 24 bytes from an application area, DAT 1 to the data buffer. In this example, the longest dbuflen is assumed to be 80 bytes. Copies data from an application into a specified field in the data buffer in memory.
The data in an application is copied to the field in the data buffer identified by its field number. Note that the field number is a unique number assigned to the field by FORMSPEC when the form is first created. The number assigned to a field by FORMSPEC does not change regardless of any changes to the field's position in the form or to its length. The field number can only be changed with the batch command, RENUMBER, as described in Section 7. The field number must not be confused with the screen order number, which is the field's position in the data buffer and corresponds to its position in the form. If the field is shorter than the data transferred to it, the data is truncated on the right. If the field is longer than the data transferred to it, the data, if any, in the remaining space in the field is not changed. If the field whose data is being replaced contained an error, VPUTFIELD clears the field's error flag, and decrements numerrs. Note that VPUTFIELD does not convert the data. To convert data from internal numeric representation to character strings, you must use VPUTtype, where type specifies the data type of the field in an application. COBOL
BASIC
FORTRAN
SPL/PASCAL
The calls shown above copy a 10-byte value from an application to field number 1 in the data buffer. Copies data from an application to the specified save field in memory. Syntax
Parameters
Discussion VPUTSAVEFIELD transfers the contents of the application variable specified by sfbuf to the save field in memory specified by sfname. If the length of the save field is less than the length specified by buflen, the right most bytes are truncated. Following a successful transfer, actualen is set to the actual number of bytes transferred to the save field in memory. Note that the contents of the save field as recorded in the forms file is not changed by a call to VPUTSAVEFIELD. Also VPUTSAVEFIELD does not convert the data moved to the save field in memory. Example COBOL These calls will transfer the contents of the application buffer SFBUF to the save field in memory specified by SFNAME. If the call is successful ACTLEN will contain the exact number of bytes transferred. Copies a numeric value of specified type from an application to a field in the data buffer in memory, converting the value to character set coded external representation.
Depending on how it is specified, this intrinsic converts integer, double, real, long, packed, zoned or yymmdd values to the external representation and copies the converted value to a particular field in the data buffer, right justified. (Note that the exact format depends on the data type of the destination field.) The destination field is identified by the field number assigned by FORMSPEC. The field to which the value is copied may be defined as a numeric field (data type NUM[n], IMPn, or DIG) or as a character field (data type CHAR).
Note that the field number never changes as long as the field exists. It is not changed when the position of the field in the form is changed, or its length or other characteristics are changed. The field number can only be changed with the batch command, RENUMBER, as described in Section 7. The field number should not be confused the screen order number, which is the position of the field in the data buffer and is based on the field position within the form. Thus, the field number provides a way to locate fields regardless of their position. If the specified field had an error, VPUTtype clears the field's error flag, and decrements numerrs. Refer to Table 6-13 “Numeric Type Conversions” under VGETtype for the format of each of the data types that may be converted. Note that COBOL does not have type real or long, and BASIC does not have a double integer data type. COBOL
BASIC
FORTRAN
The calls shown above convert an integer value of 25 in the application to the external representation and copy it to field 4 in the data buffer in memory. Copies a message to the window area of memory.
This intrinsic copies the specified message to the window area of memory for later display. Then, a call to VSHOWFORM can be used to display the message in the window area of the terminal screen, with the window enhanced as indicated by windowenh of comarea. A message copied by VPUTWINDOW overwrites any previous message in the window area, including any message copied by a previous call to VPUTWINDOW or VSETERROR. If the message is longer than the defined window length, the message is truncated on the right. If shorter, the rest of the window line is cleared. Note that the forms file may be defined with no window line for error and status messages. In this case, the message is ignored. COBOL
BASIC
FORTRAN
SPL/PASCAL
Converts a numeric value representing a date from an application and copies the converted value to a field in the data buffer in memory. Syntax
Parameters
Discussion VPUTYYYYMMDD converts the contents of the application variable to the date order of the field specified by fieldnum and copies the converted value into the corresponding field in the data buffer, right justified. The application variable should contain a numeric value in YYYYMMDD format. The YYYYMMDD format is an 8-byte ASCII value, for example, 19961225. If errors occur during conversion, cstatus is set to an error code. Refer to the VPUTtype intrinsic description in the Data Entry and Forms Management System VPLUS Reference Manual for related information. Example
These calls will convert the contents of VARIABLE to a date value and place the converted value in the data buffer corresponding to the field specified by FIELDNUM. Reads contents of current batch record into data buffer in memory.
Use of this intrinsic is demonstrated by the browse/modify mode of ENTRY. It enables a user to view the data in the batch file. VREADBATCH may also be used to bring the data from a batch file into the data buffer so that it can be retrieved by an application with the VGETBUFFER, VGETFIELD, or VGETtype intrinsics. To display the data just read onto its associated form, VGETNEXTFORM must be called before the call to VSHOWFORM. VREADBATCH reads the record (recnum) in the batch file opened by VOPENBATCH. The record is read into memory, where VREADBATCH extracts the batch record control information (refer to the VOPENBATCH description). This information includes the current form name which is moved to nfname, the delete flag which is moved to deleteflag, and the data length in bytes which is moved to dbuflen. The data buffer is not updated if the deleteflag has been set. In order to use VREADBATCH, the batch file must be on a direct-access device and must be created with fixed-length records, not variable-length records. COBOL
BASIC
FORTRAN
The calls shown above read the batch record specified by recnurm update the comarea according to the batch record information stored with the data, and put the data in the data buffer in memory. Accepts all user input from an open terminal, including data entered by pressing ENTER, or user requests made by pressing a function key. Allows look-ahead form loading.
VREADFIELDS accepts user-entered data when ENTER is pressed. It maps the data into the data buffer in memory. The data is mapped in screen order, from left to right, top to bottom. If there are any display-only fields already in the buffer, the fields read by VREADFIELDS are interspersed among the display-only fields according to the screen order. VREADFIELDS then sets lastkey to zero. Note that the keyboard is locked after the data is read (the subsequent call to VSHOWFORM unlocks the keyboard). If a function key is pressed, VREADFIELDS sets lastkey to the corresponding number: 1 for f1, 2 for f2, and so forth. The screen is not read and data is not transferred when a function key is pressed. It is, however, possible to accomplish this by enabling the AUTOREAD feature. To enable AUTOREAD, a bit must be set in the termoptions position of the comarea. For further information regarding the AUTOREAD feature, consult the Terminal Communications Area section of Appendix G. Application programs must supply the code to perform each of the functions that can be requested via a function key. The particular function assigned to a key is determined only by how the program processes the key code passed to it by VREADFIELDS (refer to Appendix A for examples of applications using VREADFIELDS). Normally, there is no time limit for VREADFIELDS, whether the intrinsic is to be terminated by the enter key or by a function key. Timeouts can be enabled in an application by setting bits in the termoptions word of the comarea and specifying a timeout interval in the usertime word of the comarea. For more information regarding user timeouts, consult the Terminal Communications Area section of Appendix G. For any terminal with touch capability, an application activates the touch feature by setting bit 0 of showcontrol to one. Then, for each time the user touches a field, VREADFIELDS returns lastkey with the field number of the touched field (as a negative number). Refer to Appendix G for the "Supported Terminal Features" list. For the data capture devices, VREADFIELDS, not VSHOWFORM, displays a form one field at a time and reads entered data, also one field at a time. Editing is performed after data for all the fields in the form has been read. VREADFIELDS sets lastkey as follows for these terminals: -1 is the ATTENTION key, 0 is the ENTER key, 1 is the "A" key, 2 is the "B" key...and 26 is the key. If a function key is pressed when entering data on the data capture devices, VREADFIELDS returns to the calling program and does not display any remaining fields. Bits 12 and 11 of the comarea item showcontrol affect form display on the data capture devices. These bits can be set as follows:
VREADFIELDS may also invoke look-ahead form loading for terminals with local form storage using the comarea item lookahead. If point-to-point data communications is being used, the next form (as defined in the forms file) is loaded into the terminal's local form storage memory while the user is typing in data) before ENTER is pressed. If multipoint or X.25 data communications is being used, the next form is loaded after the data has been read, after ENTER is pressed. If there is no room in local form storage for the next form, or if there are no available entries in the form storage directory (set with formstoresize prior to VOPENTERM and VOPENFORMF), the least recently used form could be purged from local form storage. Look-ahead form loading does not load multiple family members. If a family member of the next form is already in local form storage, this family member is changed into the required form when it is displayed. (Refer to Section 4 for more information on Local Form Storage.) If the next form does not load successfully, no error is returned. The next form is simply displayed by VSHOWFORM. Sets the error flag of a specified field and increments numerrs. If this is the first field (in screen order) with an error, it copies a message to the window area of memory for later display.
This intrinsic can be called by any program that wants to perform its own edits, either in addition to, or instead of VFIELDEDITS. VSETERROR sets the error flag associated with the specified field. If this is the first time this field has been diagnosed as having an error, VSETERROR increments numerrs; otherwise, it does not change numerrs. Thus, if a field has an error detected by a prior call to VFIELDEDITS, a call to VSETERROR for that field does not increment numerrs. However, if the touch feature is enabled, VSETERROR toggles the error flag for a specified field to clear, if it was already set, and decrements numerrs. Refer to "Coding the Touch Feature" in Appendix E. If this is the first field in the form (in screen order) that has an error, the specified message is copied to the window area of memory for later display. If you do not want to change the current contents of the window, set the length parameter to -1. To clear a message, set length to zero. Note that the field number identifies a field regardless of its position in the form. Thus, field "1" could be the third field in screen order counting from left to right, top to bottom. Using the field order number is preferable because if the fields in a form are rearranged, no modification to an application is necessary. COBOL
BASIC
FORTRAN
SPL/PASCAL
The examples above set error flags for field number "3" in the currently open form, and set up the message "THIS FIELD IS REQUIRED" to be displayed if no value is entered in the field and this is the first field (in screen order) in which an error is detected. The following examples show how VSETERROR can be used to set error flags for a field in error without writing a message to the window. COBOL
BASIC
FORTRAN
SPL/PASCAL
Allows for temporarily setting, programmatically, a new label for a function key.
VSETKEYLABEL is only a temporary setting of a new label for an individual function key. Use of this intrinsic does not change the label definition made in FORMSPEC. Note only one function key can be set with this intrinsic. The labeloption must be set to one prior to VOPENFORMF. The temporary label is displayed after the next call to VSHOWFORM. If the temporary label is global, it remains active until the forms file is closed or it is replaced by a new global label. If the temporary label is for the current form only, it is replaced when the next form is retrieved or when a new current form label is set. If no global or current form labels have been defined with FORMSPEC or no labels have been set with VSETKEYLABELS, the key label buffers are cleared before the label being defined with this intrinsic is set. COBOL
BASIC
FORTRAN
SPL/PASCAL
Allows for temporarily setting, programmatically, labels for function keys.
VSETKEYLABELS is only a temporary setting of new labels for the function keys. Use of it does not change the label definitions made in FORMSPEC. The labeloption must be set to one prior to VOPENFORMF. The temporary labels are displayed after the next call to VSHOWFORM. If the temporary labels are global, they remain active until the forms file is closed or replaced by new global labels. If the temporary labels are current form labels, they are replaced when the next form is retrieved or when new current form labels are set. If no global or current form labels have been defined with FORMSPEC or no labels have been set with a prior call to VSETKEYLABELS, the key label buffers are cleared before the labels currently being defined are set. COBOL 77 FORM-OR-GLOB PIC S9(4)COMP. BASIC
FORTRAN
SPL/PASCAL
The VSETLANG intrinsic specifies the native language to be used with an international forms file. For more information on Native Language Support, see Section 8.
This intrinsic sets the native language to be used by VPLUS at run time for an international forms file. The forms file must be opened before calling VSETLANG. Otherwise, cstatus returns a nonzero value. If VSETLANG is called to set the native language ID for a language-dependent or unlocalized forms file, an error code of -1 will be returned to errorcode. For international forms files, both cstatus and errorcode return a value of zero and the forms file is processed with the native language ID specified in langnum. Displays on the terminal screen the current form from local form storage or from the form definition buffer, any data in the data buffer, and any messages from the window buffer. Displays any labels from the key label buffer.
VSHOWFORM displays, on an open terminal screen, the form currently stored as a form image in the terminal's local form storage or in the form definition area of memory. Any enhancements specified for the form are used for the display. Data currently in the data buffer in memory is moved to the appropriate fields of the displayed form. Any message in the window buffer of memory is displayed in the line of the form selected as the status line. Also, any current form or global function key labels in the key label buffer are displayed. In order to optimize VSHOWFORM performance, only changed information is written to the terminal. Thus, if the window has not been changed by VPUTWINDOW or VSETERROR since the last execution of VSHOWFORM, or if the current form is being repeated in place, these areas are not rewritten. Also, when a form is repeating in place, only the changed values in the data buffer area of memory are written by VSHOWFORM. This will be sufficient for most applications; however, these three optimizations (form, data, window) can be overridden by setting the comarea item showcontrol as follows:
Depending on the bits set, VSHOWFORM writes a form or data or the window to the terminal whether or not it has changed. Anything that has changed is always written to the terminal regardless of showcontrol. Any combination of these bits may be set. For example, if you want to force a write of all data:
showcontrol = octal 2 Or, if you want to force the window to be written:
showcontrol = octal 4 Prior to display on terminals with local form storage, the form can be loaded into the terminal with any of the following methods:
A prior call to VGETNEXTFORM reads the form into the form definition area of memory prior to display by VSHOWFORM. The form definition includes the form image, any field editing specifications and all enhancements. The field enhancements are specified with the form definition. If a field has an error, VSHOWFORM changes its enhancement to the error enhancement defined for the form by FORMSPEC. The data buffer may contain data as a result of initialization by VINITFORM, retrieval of user-entered data by VREADFIELDS, data formatting or movement caused by editing specified with each field and executed by VINITFORM, VFIELDEDITS, or VFINISHFORM. Data may also be transferred directly to the data buffer, either from an application with VPUTBUFFER or VPUTtype, or from a batch file with VREADBATCH. The window contains any message set by VSETERROR or VPUTWINDOW. As soon as the form is displayed, VSHOWFORM normally enables the keyboard so the user can enter data. The next call is usually to VREADFIELDS, which locks the keyboard after the entered data is read. In case of consecutive calls to VSHOWFORM, the following showcontrol bit can be set:
The scenario is as follows:
This ensures that keystrokes do not change a form while it is being displayed. Consecutive calls to VSHOWFORM could be used to display a form with no fields, append another form to it, and display this second form without doing a read in between. On terminals with local form storage, VSHOWFORM first determines if the current form is already in the terminal. If the form is in local storage, it is displayed from local storage. If the form is not in local storage, it is preloaded into the terminal from the form definition area of memory depending on showcontrol, which can be set as follows:
If bit 9 is zero, the form is written directly from the form definition area of memory to the terminal screen. If bit 9 is one, the form is preloaded into local storage and then displayed from local storage. One or more forms could be purged from local storage if there is not room for the form that is being loaded. Note that purging could occur even when lookahead is set to one. On terminals with the touch feature, touch can be enabled or disabled with showcontrol, which can be set as follows:
The VTURNOFF intrinsic turns off VPLUS block mode and enables character mode access without disturbing the terminal screen. The syntax and parameter descriptions for this intrinsic are provided below.
VTURNOFF is used for momentarily switching from VPLUS block mode to character mode. This procedure is designed for use after a terminal has been previously opened by VOPENTERM or after a VTURNON.VTURNOFF reconfigures the terminal and driver for character mode operations without disturbing the screen image on the terminal. The following operations normally performed in VCLOSETERM are not performed in VTURNOFF:
Note that VTURNOFF does not close the terminal file. To close the file and completely reset the driver and the terminal, VCLOSETERM must be used.The following examples illustrate a call to VTURNOFF: COBOL:
BASIC:
FORTRAN:
SPL:
PASCAL:
The VTURNON intrinsic turns on VPLUS block mode without disturbing the terminal screen. The syntax and parameter descriptions for this intrinsic are provided below.
VTURNON is normally used in an application when the terminal is already opened by VOPENTERM, and VTURNOFF was called to switch out of VPLUS block mode. VTURNON switches the application back to VPLUS block mode without disturbing the image on the terminal screen. VTURNON reconfigures the terminal and the driver without performing the following operations which are normally performed by VOPENTERM:
Unlike VOPENTERM, VTURNON will not ask you to press the BLOCK MODE key, if you are using an HP 2640B or HP 2644 terminal when the terminal is not in block mode. The following examples illustrate a call to VTURNON using common programming languages: COBOL:
BASIC:
FORTRAN:
SPL:
Pascal:
Unloads the specified form from local form storage memory.
This intrinsic is used on terminals having local form storage. VUNLOADFORM purges the form named by the whichform parameter from terminal local form storage memory. Note that the terminal keyboard may be locked briefly while VUNLOADFORM verifies whether or not the form was purged. In case keys are pressed during this time, the terminal beeps to indicate that the keystrokes and/or entered data are lost. You can avoid this by not calling VUNLOADFORM between calls to VSHOWFORM and VREADFIELDS. COBOL
BASIC
FORTRAN
SPL/PASCAL
Writes a record to the batch file from the data buffer in memory, or deletes a record from the batch file
VWRITEBATCH writes the contents of the data buffer to the record specified by recnum in an open batch file. (The recnum must be maintained by the calling program.) VWRITEBATCH writes the following information to the batch record:
(Refer to "Record Format" in the VOPENBATCH description for a diagram of the batch record.) VWRITEBATCH may be used in both the data collection and modify modes. The data in the data buffer is entered on a particular form displayed at a terminal and then read into the data buffer by VREADFIELDS. VWRITEBATCH can then be called to write the data buffer and the record control information to the batch record specified by recnum. When data is modified, an existing batch file record is rewritten. The calling program must set recnum to the record number of this record. To mark a batch record as deleted, the deleteflag must be set to TRUE (all ones) by an application. Then a call to VWRITEBATCH sets a corresponding flag in the batch record to mark the record as deleted. Since a deleted record still exists in the batch file, it can be viewed through FCOPY or a user-written intrinsic. In ENTRY, a function key pressed by the user not only determines which record is to be viewed, but also specifies which record is to be deleted. COBOL
BASIC
FORTRAN
SPL/PASCAL
The calls shown above write the contents of the data buffer to the batch record identified by recnum. Assume the following data is in the data buffer and that it was entered on form ORDENT. (Note that the data entered on separate fields of a form is concatenated in the data buffer, with no separators.)
Assume the comarea is set as follows:
In addition, assume the batch file opened by VOPENBATCH has fixed-length records, 80 bytes long. The call to VWRITEBATCH writes the following record as the sixth record in the batch file:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||
|
|
|
|||||||||
|
|||||||||
