HP 3000 Manuals HP 3000 Manuals
Preparing an Application
Preparing a VPLUS application for use in VPLUS/Windows involves the
following process:
* Determining if the application is supported or unsupported.
* Testing the application for supportability.
* Converting the application if it is unsupported.
* Translating VPLUS forms files to create VPLUS/Windows PC forms files.
The following sections explain this process.
Supported and Unsupported VPLUS Applications
A VPLUS application communicates with the VPLUS/Windows presentation
server through existing VPLUS intrinsics. The application must meet
certain criteria to use the presentation server. Both the implementation
and operation methods of an application affect VPLUS/Windows usage.
VPLUS applications belong to one of three implementation classes. Table
2-4 lists the classes and describes the characteristics of each class.
Table 2-4. VPLUS Application Classes
--------------------------------------------------------------------------------------------
| | |
| Class | Characteristics |
| | |
--------------------------------------------------------------------------------------------
| | |
| A | Class A applications use VPLUS exclusively for all communications between |
| | the application program and the user's display device. VPLUS/Windows |
| | supports only Class A VPLUS applications. |
| | |
| | Class A applications handle the display device using only VPLUS |
| | intrinsics, such as VOPENTERM, VREADFIELDS, VSHOWFORM, and VCLOSETERM. |
| | Consequently, you do not have to alter Class A application code to use |
| | VPLUS/Windows. |
| | |
--------------------------------------------------------------------------------------------
| | |
| B | Class B applications supplement VPLUS calls with additional methods of |
| | communication between the application program and the display device. |
| | |
| | Normally, the additional communications involve only application data, |
| | and there are no imbedded terminal control escape sequences. Class B |
| | applications can use DISPLAY and ACCEPT (COBOL), WRITELN and READLN |
| | (Pascal), or FWRITE and FREAD (MPE) for these additional communications. |
| | Class B applications could achieve the same objective by using only |
| | supported VPLUS features. |
| | |
--------------------------------------------------------------------------------------------
| | |
| C | Class C applications, like Class B applications, supplement VPLUS calls |
| | with additional methods of communications between the application program |
| | and the display device. |
| | |
| | Unlike Class B applications, Class C applications typically imbed |
| | terminal escape sequences. Class C applications can also directly |
| | manipulate the communications environment using MPE intrinsics such as |
| | FCONTROL, or by using VTURNOFF and VTURNON. Class C applications can |
| | issue MPE commands (through the COMMAND intrinsic) that communicate with |
| | the user's display device. Supported VPLUS features may not be available |
| | to achieve all of the objectives of class C applications. |
| | |
--------------------------------------------------------------------------------------------
Supported and Unsupported VPLUS Intrinsics. Most of the VPLUS intrinsics
function the same when running in the VPLUS/Windows environment. Some of
the intrinsics execute on the PC and the HP 3000; all others execute only
on the HP 3000.
The following intrinsics execute on both the PC and the HP 3000:
* User interaction intrinsics:
VOPENTERM
VCHANGEFIELD
VSHOWFORM
VPLACECURSOR
VREADFIELDS
VCLOSETERM
* Forms file access intrinsics:
VOPENFORMF
VGETNEXTFORM
VCLOSEFORMF
The following intrinsics bypass their function when used with
VPLUS/Windows:
VTURNOFF
VTURNON
VLOADFORM
VUNLOADFORM
The following intrinsics function differently for VPLUS/Windows:
VCLOSETERM Sets up the presentation server for termination of
application interaction with the PC user, instead of
closing a terminal file.
VOPENFORMF Opens the PC forms file and checks for synchronization
with the HP 3000 forms file.
VOPENTERM Sets up the presentation server for interaction with the
PC user, instead of opening a terminal file. The
COMAREA variable identifier returns a value in the range
of 100 to 150.
VPLACECURSOR Places the cursor on a specified field in the form
window on a PC using Microsoft Windows, instead of
writing to the terminal.
VPRINTSCREEN Returns a value of 22 in CSTATUS of the COMAREA with the
accompanying message, The intrinsic called is not
supported for this terminal. VPLUS/Windows does not
support this intrinsic.
VREADFIELDS Reads in user data from a form on a PC using Microsoft
Windows instead of reading a terminal file.
VSHOWFORM Displays a form on the PC using Microsoft Windows
instead of writing to a terminal file.
Unsupported Operation Methods. VPLUS/Windows does not support certain
operation methods. You cannot do the following:
* Use a master application to start your application program and assign
it to a user device.
* Use a file statement to redirect VPLUS communications to another PC
when running your application from VPLUS/Windows.
* Use a file statement to redirect VPLUS communications to the
presentation server on a PC when running your application from a
terminal.
Testing for Application Supportability
In order to classify an application as supported or unsupported in
VPLUS/Windows, you must understand the implementation and operating
environment of the application. You can run an I/O compatibility test to
initially assess the application for VPLUS/Windows supportability.
When running the test, you can separate the two logical terminal devices
defined by every VPLUS application program: the VPLUS device and the
session device. The VOPENTERM termfile variable of the COMAREA parameter
defines the VPLUS device. $STDIN and $STDLIST comprise the session
device.
Test Limitations. The I/O compatibility test cannot:
* Confirm that an application is supportable for VPLUS/Windows; it only
confirms that an application does not meet Class A requirements.
* Measure the specific application functions that you do not attempt to
test.
* Measure the application functions for which you have not created
specific conditions. You must test these conditions using other test
methods.
* Detect unsupported applications that:
* Use the terminal file number in the VPLUS COMAREA for non-VPLUS
I/O calls.
* Start up a terminal using I/O redirection.
* Use unsupported VPLUS procedures.
Running the Test. You could execute your program using one of the
following separation methods:
* VPLUS device method
* Session device method
VPLUS Device Method. Perform the following steps to use the VPLUS device
method:
1. Redirect the VPLUS logical device to a second terminal using a
file statement for termfile. Refer to Appendix E of the VPLUS
Reference Manual (32209-90001) for information about redirecting
the VPLUS logical device.
2. Determine whether your application meets Class A requirements.
Your application does not meet Class A requirements if you must
provide input on your session device, or if output appears on your
session device during the test.
Session Device Method. Perform the following steps to use the session
device method:
1. Assign $STDLIST to a file and $STDIN to $NULL in the RUN command
of your program.
2. Determine whether your application meets class A requirements.
Your application does not meet class A requirements if your
application terminates abnormally without input for $STDIN, or if
the application creates output in $STDLIST.
Example of Methods. One example of applying these separation methods is
to test the VPLUS data entry application, ENTRY.PUB.SYS. Either method
terminates ENTRY in an error state. To use the session device separation
method described above, assign $STDLIST to the file XOUT and redirect
$STDIN to $NULL as shown:
BUILD XOUT;REC=-80,16,F,ASCII
RUN ENTRY.PUB.SYS;STDLIST=XOUT;STDIN=$NULL
After running the test, the ENTRY banner line in XOUT would appear,
followed by:
ENTER FORMS FILE NAME AND PRESS RETURN:
Terminal access failed unexpectedly.
**** PROGRAM ERROR #18 :
PROCESS QUIT
.PARAM = 3
ABORT: ENTRY.PUB.SYS
Following this output, information about the specific system locations of
the abort would appear.
The information from XOUT indicates that ENTRY fails to run when $STDIN
is redirected to $NULL. This failure occurs because ENTRY prompts the
user for information prior to the forms-based user interface. Therefore,
ENTRY, like any application that requires $STDIN or outputs data to
$STDLIST, does not meet Class A requirements.
Converting an Unsupported Application
If your application is currently unsupportable in VPLUS/Windows, you can
convert your application for usage with VPLUS/Windows. Your application
can conform to Class A requirements if you are able to replace non-VPLUS
display device I/O operations with supported VPLUS intrinsics to interact
with the display device. Alternatively, you may be able to create a
Class A compliant application. This type of application incorporates
both its original operation method and a VPLUS/Windows compatible
operation method.
A compliant application can control the operation method with an external
technique. For instance, ENTRY was originally not a Class A application.
However, ENTRY has now been updated as a Class A compliant application.
You can run it in VPLUS/Windows using an INFO string to replace the
initial prompts and redirecting $STDLIST to a file or to $NULL, as shown
in the following example:
RUN ENTRY.PUB.SYS;INFO="$FORM=myff $BATCH=mybatch";STDLIST=XOUT
Conversely, some applications can successfully control the appropriate
operation method internally. The COMAREA variable identifier returned by
VOPENTERM can be used to recognize the presentation server. This
variable informs the VPLUS application whether or not the current device
is a PC bit-mapped display. Identifier 100 is currently used for
VPLUS/Windows. The value range 100 to 150 is reserved for presentation
servers. Appendix G of the VPLUS Reference Manual (32209-90001) provides
a list of other supported identifiers.
Table 2-5 describes several possible non-compliant application elements
and the corresponding modifications for compliance.
Table 2-5. Conversion of Selected Non-Compliant Applications
---------------------------------------------------------------------------------------------
| | |
| Non-Compliant Application | Suggested Modification |
| Element | |
| | |
---------------------------------------------------------------------------------------------
| | |
| Your application uses | Add a check for the CSTATUS value of 22. Also, provide |
| VPRINTSCREEN. | a message in the window line informing the user that the |
| | requested function is unavailable for this device. You |
| | can possibly substitute VPRINTFORM in certain cases. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Application progress messages | Use VSHOWFORM for the messages. Include a simple form |
| go to $STDLIST. | in your forms file with a large field for messages, or |
| | use the window line of the current form. Open the VPLUS |
| | resources before your first progress message, and do not |
| | close them until all user communication is complete. |
| | |
| | Bypass the messages, if desired, by assigning $STDLIST |
| | to $NULL or to a file built large enough to contain all |
| | possible messages. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Abnormal termination messages | Use VSHOWFORM as described above if the messages are |
| go to $STDLIST. | caused by a user input problem, a database problem, or a |
| | file problem. If the problem is related to VPLUS, |
| | continue to use $STDLIST, but redirect it to a file for |
| | later problem diagnosis. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Your application prompts the | Do one or more of the following: |
| user for run-time parameters. | |
| | |
| | Use VSHOWFORM with the prompt text and input fields on |
| | a form followed by VREADFIELDS to capture the |
| | information. |
| | |
| | Use an external file containing the needed parameters. |
| | |
| | |
| | Use a JCW if the parameter is numeric. |
| | |
| | Use the INFO string in the RUN command. |
| | |
| | Use file statements if the parameters are file names. |
| | |
| | |
---------------------------------------------------------------------------------------------
| | |
| Your application supports | Add a check for identifier in the COMAREA. When |
| printing to a slave printer. | identifier is in the range from 100 to 150, use |
| | VSHOWFORM with a message in the window line informing |
| | the user that the requested function is unavailable for |
| | this device. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Your application optionally | Use VSHOWFORM to display the report data. Include a |
| outputs a report to the | form in your forms file with 24 display-only fields of |
| terminal without using VPLUS | 79 characters each using invisible field delimiters. If |
| between VPLUS form | your report is 80 characters wide, consider using a |
| interactions. | large multi-line field. Use line 24 to end the |
| | multi-line field. Include function keys with choices to |
| | end the display or continue the display as appropriate. |
| | Use VREADFIELDS to capture the function selected. |
| | |
| | Consider devoting more than 24 lines to the report if |
| | all of your terminals have sufficient memory. Or |
| | consider including two forms in your forms file: a |
| | 24-line form and a longer form. Use identifier in the |
| | COMAREA to control which form you retrieve and how much |
| | data you put into the buffer. VPLUS/Windows and large |
| | memory terminals enable a user to scroll a long form for |
| | review of the data. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Your application has a small | Use a pair of forms as a family. Make the selection |
| VPLUS form for selecting | fields as input for one member and display-only for the |
| information to be retrieved, | other member. Design the report area of the form as |
| and you display a report below | described above. Devote a key label for toggling |
| it without using VPLUS. | between the selection member and the report member. |
| | (The VPLUS ENTRY application provides an example of |
| | toggling between the Collect and Browse functions.) |
| | |
---------------------------------------------------------------------------------------------
Translating VPLUS Forms Files
To prepare HP 3000 VPLUS forms files to run in the VPLUS/Windows
environment, you must translate them to PC-based forms files.
Translating forms files requires approximately one-tenth of the time
required to compile forms files. After you have translated the forms
files, you can then copy them to the PC.
The VPLUS/Windows utility VFFXLTPC translates existing
HP 3000 VPLUS slow and fast forms files to VPLUS/Windows PC forms files.
Besides translating forms files, the utility can also optionally generate
a help facility cross-reference file and can enable you to optionally
specify a language for an international forms file.
Running the Utility. Perform the following steps to translate an HP 3000
forms file:
1. Create file equations for the XLTIN input source file and the
XLTOUT output destination file as shown:
FILE XLTIN=input_file_name
FILE XLTOUT=output_file_name
If you do not specify a file equation for the input file using the
formal designator XLTIN, the utility attempts to open a file
called XLTIN. If this file does not exist, the utility aborts with
an error.
If the file equation for XLTOUT does not exist before you run
VFFXLTPC, the utility creates the file XLTOUT. If XLTOUT already
exists when you run VFFXLTPC, the utility creates a temporary file
with the same name. If both a permanent and temporary file with
the same name already exist, the utility generates an error and
aborts without saving the output file.
2. Run VFFXLTPC as shown:
RUN VFFXLTPC.PUB.SYS
If no errors occur during translation, VFFXLTPC displays the
following message:
END OF TRANSLATION
NUMBER OF FORMS IN FORMS FILE: nnnn
NUMBER OF FORMS TRANSLATED: nnnn
To produce more comprehensive processing messages, specify SETJCW
VFFXLTPCLIST=1 before running VFFXLTPC.
3. Copy output_file_name to the PC. The PC file name must match the
name of the original VPLUS forms file with an added MS-DOS
extension of VWF as shown:
input_file_name.VWF
Running the Utility with Options. The procedures in the following
sections enable you to run VFFXLTPC to do the following:
* Generate a help facility cross-reference file.
* Specify a language for an international forms file.
* Combine both of these options.
Generating a Help Facility Cross-Reference File. Perform the following
steps to generate a help facility cross-reference file. After performing
the steps, refer to "Providing Context Numbers" in Chapter 4 for
information about using the cross-reference file and its contents.
1. Create the following file equation for the cross-reference file:
FILE XREFFILE=cross_reference_file_name
2. Perform step 1 in "Running the Utility."
3. Run VFFXLTPC as shown:
{ALL }
RUN VFFXLTPC.PUB.SYS;INFO="XREF={FORM}"
{NONE}
Definitions for XREF parameters are as follows:
ALL Generates a cross-reference file for all forms, key
labels, and fields.
FORM Generates a cross-reference file for only form-level help.
NONE Does not generate a cross-reference file.
If you specify anything other than these parameters, the utility
aborts with an error message.
If you specify ALL or FORM and a file equation for XREFFILE does
not exist, the output goes to a file named XREFFILE.
If the utility cannot create a file name XREFFILE, it terminates
without creating the cross-reference file. Cross reference
generation begins after the PC forms file has been created.
Unexpected termination of the cross-reference generation does not
affect the translated forms file.
4. Copy cross_reference_file_name to the PC. The PC file name must
have an MS-DOS extension of H as shown:
cross_reference_file_name.H
5. Perform step 3 in "Running the Utility."
Specifying a Language for an International Forms File. Perform the same
steps as in "Running the Utility," except substitute the following
instructions in place of step 2:
Run VFFXLTPC as shown:
RUN VFFXLTPC.PUB.SYS;INFO="LANGUAGE=lang_id"
Provide either a name or a number for lang_id. The language defaults
to the language of the forms file if you do not include this parameter.
If the forms file language is international and you do not specify a
language in the INFO string, the user interface language configured on
your system is used. If the forms file language is international and
you specify international in the INFO string, the program aborts with
an error.
Combining Both Options. If you want to specify both options, you can
combine them in the same RUN command after performing the required
preparatory steps documented for both options. Enter the INFO string
portion of the command as follows:
{ALL }
INFO="XREF={FORM} LANGUAGE=lang_id"
{NONE}
Translation Utility Limitations. The utility cannot:
* Translate a forms file that has never been compiled. A warning
appears if you have modified the VFORM file since it was last
compiled.
* Translate more than 512 forms in a forms file.
* Translate forms files created before version B.03.03 that have not
been adjusted. Refer to Appendix H of the VPLUS Reference Manual
(32209-90001) for the adjustment procedures.
* Translate KSAM forms files. You must convert KSAM files to forms
files with the file code of VFORM. Refer to Appendix H of the VPLUS
Reference Manual (32209-90001) for the conversion procedures.