VPRINTSCREEN Intrinsic

A new intrinsic, VPRINTSCREEN, provides the capability to print the entire contents of a terminal screen during VPLUS execution. Currently, VPLUS provides the intrinsic VPRINTFORM which prints the current form with the data contained in the form data buffer; function keys, appended forms, line drawing characters, etc., are not printed. With VPRINTSCREEN, these limitations no longer exist.

The largest demand for this functionality has been from documentation and training departments. In the past, the only method for obtaining a complete "snapshot" of a screen was through the use of the internal printers available on some HP terminals.

There are two approaches a user can take to produce copies of VPLUS screens. One is to incorporate the use of VPRINTSCREEN into an end-user application so that screen images can be captured at run time. This allows actual screen and data to be captured in production mode. The other method is to develop a simple utility which would only be used to produce hard copies of screens. The utility should allow data to be entered into the screens before calling VPRINTSCREEN to produce the image. The advantage of this method is that it removes the overhead of using VPRINTSCREEN from the application, but still provides a mechanism for including reproductions of the screens and data in product literature.

The demo program, VPRTDEMO, is an example of this type of utility. Refer to the section "Viewing the VPRINTSCREEN Demo" for specifics on how to access and use the demo program. Any user interested in the VPRINTSCREEN intrinsic should use this demo with existing forms before attempting to modify existing applications.

The remainder of this article will concentrate on the process of calling VPRINTSCREEN from a user program. This procedure was implemented using the Pascal heap procedures to perform stack allocation. This introduces a high risk of conflict for applications which use the DLSIZE intrinsic for stack allocation. In the case of VPLUS, DLSIZE is used by the existing intrinsics when the application is written in COBOL, FORTRAN/66, or SPL. However, since VPRINTSCREEN always uses the heap procedures, applications written in one of these specified languages must follow two rules when calling VPRINTSCREEN.

The language id in the COMAREA must be set to 5
The INTRINSIC calling mechanism must be used when calling the VPLUS intrinsics from the main and all interacting parts of the application. For example, with COBOL the application must use:
CALL INTRINSIC <intrinsic name>

Refer to Appendix E of the VPLUS Reference Manual, the COBOL Reference Manual and the Pascal Reference Manual for more information on these calling mechanisms.

For applications which use a language-id of 5 in the VPLUS COMAREA (Pascal, FORTRAN/77, HPBUSINESS BASIC), VPLUS uses the HEAP procedures for stack allocation. The new intrinsic can be called in the standard format from an application of this type.

VPRINTSCREEN

VPRINTSCREEN records the contents of the current screen to an off-line list device. A documentation option allows formatting for printing to a laser printer (See Modes of Operation). A VPLUS supported terminal is required during execution. TDP is required for the laser printer output.

VPRINTSCREEN {COMAREA, READSIZE}

Parameters

COMAREA

The following COMAREA items must be set before calling VPRINTSCREEN (unless previously set):

CSTATUS: Set to zero.
COMAREALEN: Set to the total number of 2-byte words in COMAREA.
PRINTFILENUM: Set to the file number of the list file to which form is printed. If set to 0, VPRINTSCREEN opens the device "LP" as the list file, and sets PRINTFILENUM to the file number of the opened list file.
VPRINTSCREEN may set the following COMAREA values:
PRINTFILENUM: If VPRINTSCREEN opened the list file, set to the file number of the opened file.
CSTATUS: Set to a nonzero value if call is unsuccessful.
FILEERRNUM: Set to the MPE error code if an MPE file error is encountered.

READSIZE

2-byte INTEGER. Reserved for system use; must be 0.

A possible implementation of this feature would be to define a function key which is available to the user for printing the screen contents in any transaction. This feature would be useful for providing immediate output of documents and data during production. This new intrinsic is demonstrated with the program VPRTDEMO. See the section titled "Viewing the VPRINTSCREEN Demo" in this note for directions on obtaining the demo.

Modes of Operation

VPRINTSCREEN operates in two modes; normal and documentation. Both of these modes are discussed in detail below.

Normal Mode

This is the default calling mode of VPRINTSCREEN. When called, the value is the PRINTFILNUM 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 PRINTFILNUM. 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:

:FILE FORMLIST;DEV=LP;REC=-80

A user may change any of these characteristics with a :FILE command.

It is recommended that VPRINTSCREEN and VPRINTFORM not be used together within the same program. Since the same list file is used for both listings, output from the two calls will be intermixed.

Another visible difference between VPRINTFORM and VPRINTSCREEN is that VPRINTFORM gives you the option to underline fields. This option is NOT available with VPRINTSCREEN (LP mode).

A PAGE EJECT is performed each time VPRINTSCREEN is called (at the completion of the print operation).

Documentation Mode

The output provided in this mode of operation is intended for manual writers and/or programmers who are familiar with TDP. The user must already have TDP on their system or must purchase it to use VPRINTSCREEN in this mode.

In documentation mode, VPRINTSCREEN in conjunction with TDP, provides the capability to print screen contents on a laser printer (HP2680A and HP2688A). With this more, borders, field highlighting (other than color), alternate character sets, and active function keys are captured and converted to the appropriate font for printing on the laser printer. Documentation node is enabled by setting a JCW before running the program:

:SETJCW VPRINTJCW=1

When VPRINTJCW is set to "1", the list file, FORMLIST is NOT opened. Instead, a temporary ASCII disc file, EPOCLIST, is created (or appended to, if it already exists). This file can be saved and renamed on completion, and then input to TDP and "finaled". A documenter can also add text to the file, or have a separate file, and use the TDP "include" statement to access the screens. (Refer to the TDP Reference Manual for a detailed discussion on USE and INCLUDE files).

In order to print the forms to a laser printer, an environment file must be created. (See the IFS/3000 Reference Guide). We have supplied sample environment files which can be used if the user does not already have his/her own files. If other environment files are used, they must include the font ids shown under LIMITATIONS> The supplied files are:

VENV80: environment file for the HP2680 laser printer
VENV88: environment file for the HP2688 laser printer
VSETUP: TDP include file which sets parameters for TDP listings and references the environment files
VEPOCUSE: TDP USE file which separates each screen contained in EPOCLIST into separate files
VPRTDEMO: Demo program which demonstrates the use of the VPRINTSCREEN intrinsic




	NOTE: See the section titled "Viewing the VPRINTSCREEN Demo" for information on obtaining these files.

Printing Screens from TDP

By default, EPOCLIST uses the VSETUP file to reference the supplied environment files. These files must be accessible by TDP before EPOCLIST can be printed. If a different environment file is used, EPOCLIST must be modified to reference the appropriate environment file. In addition, the font definitions from VENV80 and VENV88 must be included in the environment file used. (Refer to the fonts listed in the Limitations section).

Following are the steps involved to print the entire contents of EPOCLIST to a laser printer:

:PURGE (or :RENAME)EPOCLIST
:SETJCW VPRINTJCW = 1
:Run your application program.
Access the PRINT function wherever it's available to save screen contents in EPOCLIST. Remember, all the data entered by the user will also be saved as part of the screen.
Exit application.
:SAVE EPOCLIST (EPOCLIST is the temporary file which was created in the above step. It contains the contents of all the screens printed).
:RENAME EPOCLIST, <new name> If not renamed, the next time the application is run, the output will be APPENDED to the existing file.
:RUN TDP.PUB.SYS
Execute the following command:
"FINAL from <new name> to *HP2680" or "FINAL from <new name> to *HP2688".
These final two steps could be specified in a job stream. The screens will be printed out one per page.

Merging Screens with a TDP File

Instead of printing the screens out separately, you may want to include them into an existing TDP file. A special file, VEPOCUSE, is provided to facilitate the user in this task. The VSETUP file must be included as one of the first statements of your TDP document file. It will set up the reference to the correct environment file necessary for printing the screens in EPOCLIST.




	NOTE: If you want to use a difference environment file, you must include the font definitions from `VENV80` or `VENV88` in your environment file. (Refer to the fonts listed in the Limitations section).

The first step is to separate the screens in EPOCLIST. VEPOCUSE can be used to do this by following these steps:

:RUN TDP.
Clear workspace.
USE VEPOCUSE.
Answer the prompts: filename, number of occurrences, and desired PREFIX. VEPOCUSE will then split the file into 'n' files, all prefixed with the PREFIX entered.
Text in your document, and include the appropriate screen file in the appropriate location.

It is recommended that the screen files are "included" into the file, because EPOCLIST has a record size of 168 bytes, and most document files are set to 80 bytes.

Sample EPOCLIST File

   *>>DATE:FRI,MAY 3, 1986, 11:19AM 
   if main in hpvsetup.pub 
   image 28 
   need 28 
   >>>>>screen formatting commands<<<<< 
   *>>END VPRINTSCREEN B.04.20

Sample EPOCLIST

Figure L-4 Sample EPOCLIST Screen from TDP

Limitations

The Intrinsic VPRINTSCREEN

Procedure calls must be modified in order to call the intrinsic from a language which does not use a VPLUS language id of 5 in the COMAREA. (COBOL, SPL, FORTRAN/66).
Uses additional stack resources.

The Environment Files

Native Language support is NOT available for VPRINTSCREEN. To print a screen in another language, a LOCALIZED environment file must map to the following fonts:
- c = full bright
- g = half bright inverse video
- d = normal l = line draw
- m = math
There is no distinction between fullbright and halfbright provided with the current environment files. However, the code is set up to distinguish between them. (See the above fonts). Currently, the fontids "c" and "g" map to the same font in the VSETUP file.
Screen images cannot be scaled. In other words, fonts are provided in one size only. A "scaled font" environment file which maps to the same fonts above, would need to be created.
Sample files are provided. They can be modified or the user can create their own using the font ids defined above.

Use of TDP

The maximum TDP record size is 168 characters. A single line of a display screen can contain multiple escape sequences, and easily exceed this limit (e.g., line draw, full bright, many single character fields). If this limit is exceeded, the line may be truncated.
TDP Macros '5' through '9' are used to alleviate this truncation, but some screens are complicated enough to reach this limit anyway. If you use your own macros 5-9 (other than as temporary macros), some inconsistencies may exist when merging text and screens.
TDP may indicate errors have occurred, when in fact, there are no errors. The most common messages are: "Unrecognizable command" and "x Characters have been truncated".

Viewing the VPRINTSCREEN Demo

The new VPLUS intrinsic, VPRINTSCREEN, can be demonstrated with the program VPRTDEMO. You can simply run VPRTDEMO and specify a forms file name. The application will present the forms in alphabetical order and call the VPRINTSCREEN intrinsic when the user selects the PRINT function key, F3. At the beginning of execution, the user will have the option to automatically print all forms in the forms file.

Several sample and demo files have been supplied as examples for the user. They are contained on the installation tape in the HPPL89 account and HP32209 group. They should be restored to a local group and account. Some name modifications may be necessary (see below).

VENV80

This is the environment file required for printing to the HP2680 printer.

VENV88

This is the environment file required for printing to the HP2688 printer.

VSETUP

This is a TDP "include" file which selects and sets up the proper environment for the printer selected. This file should be modified so the references to VENV80 and VENV88 are properly qualified by the GROUP.ACCOUNT they reside in. If the document you are printing resides in a separate group and account from VSETUP, then a file equation must be issued to reference VSETUP. This also applies if the user renames the VSETUP file to a local name. In either case a file equation must be issued, for example:

:FILE VSETUP = VSETUP.MYGROUP.MYACCT -OR- :FILE VSETUP = MYSETUP.MYGROUP.MYACCT

VEPOCUSE

This is a TDP "use" file, potentially needed when merging text with screens.

VPRTDEMO

This is a demo program which demonstrates the use of the VPRINTSCREEN intrinsic. It can be run in normal or documentation mode. Following are instructions for running the demo.

Running VPRTDEMO

:PURGE (or :RENAME) EPOCLIST
:SETJCW VPRINTJCW = 1
:RUN VPRTDEMO.
Accessing the PRINT function wherever it's available to save screen contents in EPOCLIST. Remember, all the data entered by the user will also be save as part of the screen.
Exit VPRTDEMO.
:SAVE EPOCLIST (EPOCLIST is the temporary file which was created in the above step. It contains the contents of all the screens printed).
:RENAME EPOCLIST, <new name> If not renamed, the next time the application is run, the output will be APPENDED to the existing file.
:RUN TDP.PUB.SYS
Execute the following command:
"FINAL from <new name>to *HP2680" or "FINAL from <new name>to *HP2688". These final two steps could be specified in a job stream. The screens will be printed out one per page.

If you answered "Y" to the automatic print prompt, the forms will be displayed and printed in alphabetic order. At completion, you will have EPOCLIST. If the VPRINTJCW is not set, then a FORMLIST file will be created.

If manual print mode was selected, then the first form in alphabetic order is displayed. If local function keys were defined for the form, then these keys will be displayed.

However, the action performed by VPRTDEMO when a key is selected is defined below:

Key 1 = FIRST FORM: <displays first form in file>
Key 2 = not defined
Key 3 = PRINT: <prints screen design to EPOCLIST or FORMLIST>
Key 4 = REFRESH: <refresh current screen design>
Key 5 = PREV FORM: <displays previous form in file>
Key 6 = NEXT FORM: <displays next form in file>
Key 7 = SELECT FORM: <prompts for name of form to be displayed>
Key 8 = EXIT: <exit VPRTDEMO>