Transferring Window Files

Creating a Transfer File

The window files that you design in Window Painter are compiled files; before a window file can be transferred to another environment, a user-readable source code version must be created. This user-readable file is called a transfer file, and is created using the transfer file option of Window Painter.

This Window Painter option automatically creates a new member of the PDS allocated to ddname TRF; the PDS must already have been allocated (with LRECL between 80 and 132 and RECFM FB). However, it is not necessary to create the PDS if you use the transfer file during the current FOCUS session: Window Painter temporarily allocates the PDS.
For information about the transfer files created by FOCUS Window Painter in other operating environments, see the appropriate FOCUS Users Manual for those environments.

To convert a window file to a transfer file, go to the Window Painter Utilities Menu and select:

Create a transfer file

You are prompted for the name of the new transfer file. Enter a member name; it can have the same name as the window file, or an entirely new name.

Note that you should not give the transfer file a name already assigned to a window documentation file. Also, you should not give the transfer file a name already assigned to an existing transfer file unless you want to merge the two files. See the appropriate operating environment topic in the Overview and Operating Environments manual for more information about duplicate window transfer and window documentation file names.

You are asked to select which window(s) you want to transfer. Select

All

to transfer all of the windows in the current window file, or select any single window in the file. This is the last step in creating a transfer file.

Note that you can merge transfer files: if a transfer file already exists for your window file, and you only need to add a new window to it, you can give the new transfer file the same name as the old one, and select the new window. Window Painter merges the source code for the new window into the existing file, so that you have a single complete transfer file.

Transferring the File to the New Environment

Once the transfer file exists, it can be transferred to the new environment using FTP.

Editing the Transfer File

In this section:

Window facility features introduced in one FOCUS release may not be fully supported in earlier releases. Because different operating environments may be running different releases of FOCUS, the transfer file created by the FOCUS Window facility in one environment may contain features not fully supported by the Window facility in another environment.

If your transfer file contains Window facility features not fully supported in the new environment, you may need to remove or fine-tune those features. If the new environment supports features are not supported in the original environment, you can add those features to the transfer file. Adding, removing, and fine-tuning features can be done by simply editing the transfer file.

Top of page

The Format of the Transfer File

The transfer file is a user-readable source code listing of all of the windows and features that were included from the original window file. You can remove or fine-tune an unsupported feature by simply editing or deleting the appropriate line in the transfer file. You can accomplish this by using TED or any other editor.

Each transfer file contains:

One set of window file attributes describing the file.
For each window defined in the file, one set of window attributes describing that window.
For each line in each window, one set of attributes describing that line.

If any attribute is not specified in the transfer file, it defaults to a value of zero or blank (depending on whether the value is normally numeric or alphanumeric).

Top of page

Reference: Transfer File Syntax: Window File Attributes

Attribute	Description
FILENAME	The name of the original window file.
DESCRIPTION	A comment field describing the file.
WINDOWNAME	The name of the window.
TYPE	The type of window: Vertical menu Text input window Text display window Horizontal menu File names window Field names window File contents window Return value display window Execution window Multi-input window
COMMENT	A comment field describing the window.
TRANSLATE	Type of input for text input windows (Type 2). 0 Allow mixed-case input. 1 Allow numeric input only. 2 Translate input to uppercase.
ROW	The row number of the upper left corner of the window.
COLUMN	The column number of the upper left corner of the window.
HEIGHT	The height of the window data (the number of lines of window data, not the height of the actual window frame). If there are more data lines than what fits in the window frame, use the PF7 and PF8 keys to scroll the window.
TEXT LINE	Position of menu text. Values are: +1, +2, -1, -2.
WIDTH	The width of the window frame, not including the border.
INPUT FIELDS	Fields for multi-input windows.
WINDOW	The number of lines in the actual window frame (not the number of lines of window data). This does not include borders.
POPUP	Sets the pop-up feature. 0 This is not be a pop-up window. 1 This is a pop-up window.

Top of page

Reference: Transfer File Syntax: Window Attributes

Attribute	Description
BORDER	Sets the window border. 0 There is no window border. 1 There is a window border. 2 There is a window border. Options 1 and 2 both result in a basic window border.
HEADLEN	Length of the window heading. If this value is 0, there is no heading.
RETURN	Sets the line break feature for use with return value display windows. 0 Line break is not used. 1 New line before this return value. 2 New line after this return value. 3 New line before and after this value.
MULTI	Sets the multi-select feature. 0 This is not a multi-select window. 1 This is a multi-select window.
HEADING	The text of the window heading.
HELP	The name of the help window for this window.
HELPFILE	The name of the window file that contains the help window.
DISPLAY	The name of a window to be displayed at the same time this one is displayed. There can be up to 16 DISPLAY values for each window. This attribute is optional.
HIDE	The name of a window to be hidden when this one is displayed. There can be up to 16 HIDE values for each window. This attribute is optional.

Top of page

Reference: Transfer File Syntax: Window Line Attributes

Attribute	Description
DATA	A line to be displayed in the window (for example, a menu choice in a vertical menu Window, or a line of text in a text display window). The data can include amper variables (including &windowname).
GOTO	The name of the window to go to if this line is selected by the user. The value can be an amper variable (including &windowname). If the value is blank, and this line is selected, Windows returns to Dialogue Manager.
VALUE	The return value supplied if this line is selected by the user. This value is placed in the amper variable &windowname, where windowname is the name of the window. For file names windows (TYPE = 5), this is the file selection criteria (including asterisks) of the file names to be displayed. For field names windows (TYPE = 6), this is the name of the Master File whose fields are displayed. For file contents windows (TYPE = 7), this is the name of the file whose contents are to be displayed.

Attribute

Description

DATA

A line to be displayed in the window (for example, a menu choice in a vertical menu Window, or a line of text in a text display window). The data can include amper variables (including &windowname).

GOTO

The name of the window to go to if this line is selected by the user. The value can be an amper variable (including &windowname). If the value is blank, and this line is selected, Windows returns to Dialogue Manager.

VALUE

The return value supplied if this line is selected by the user. This value is placed in the amper variable &windowname, where windowname is the name of the window.

For file names windows (TYPE = 5), this is the file selection criteria (including asterisks) of the file names to be displayed.

For field names windows (TYPE = 6), this is the name of the Master File whose fields are displayed.

For file contents windows (TYPE = 7), this is the name of the file whose contents are to be displayed.

Top of page

Operating Environment Considerations

When you transfer a window file to a mainframe operating environment from a different environment, differences in hardware and operating software may require that you make changes to the file. These changes are discussed below.

Screen position. Windows should not begin in row 1 or in column 1. If you transfer a window with these row or column positions, truncation occurs. Adjust the ROW and COLUMN attributes if necessary.
Screen size. Windows should not have more than 22 rows or 77 columns. Windows that extend beyond the end of the terminal screen is automatically truncated without any warning message.
This is important to note if you are transferring a window file from an environment where the screen size differs from that in the mainfram envrionment. Adjust the ROW and COLUMN attributes if necessary.

Window Position. Column 1 of vertical menu, horizontal menu, multi-input and text display windows cannot be used. Window text must begin to the right of column 1.
Function keys. Windows transferred from other environments may refer to function keys not present in the mainframe environment. Change function key references if necessary.
Blank lines. Blank line are acknowledged by Window Painter.
Colors and Border Types. The use of colored windows and background and multiple border types is not supported.
File Naming Conventions. File naming conventions differ in different operating environments. When transferring a file from some environments, the Window facility automatically translates references to FOCEXECs, Master Files, and error files, as shown below. You must change other file references yourself when you edit the transfer file.

PC or UNIX Extension	Mainframe ddname
.FEX	FOCEXEC
.MAS	MASTER
.ERR	ERRORS

Top of page

Example: Sample Transfer File

To illustrate the transfer file format, part of the transfer file for the SAMPLE window file is shown below (SAMPLE is described in the tutorial). The MAIN and EXECNAME windows from the file are included in the example.

FILENAME=SAMPLE
DESCRIPTION='Sample file for windows tutorial'
WINDOWNAME=MAIN,TYPE=1
COMMENT='User can report, graph, or exit.'
ROW= 6,COLUMN=23,HEIGHT= 7,WIDTH=38,WINDOW= 7,POPUP= 0,BORDER= 
2,HEADLEN=28
RETURN=0
MULTI=0
HEADING='Would you like to:'
DATA='   '
$
DATA='         Create a report?'
GOTO='EXECTYPE',VALUE='RPT '
$
DATA='   '
$
DATA='         Create a graph?'
GOTO='EXECTYPE',VALUE='GRPH'
$
DATA='   '
$
DATA='         Exit?'
GOTO='        ',VALUE='XXIT'
$
DATA='   '
$
DISPLAY=BORDER   ,$
DISPLAY=BANNER   ,$
WINDOWNAME=EXECNAME,TYPE=5
COMMENT='Select an existing FOCEXEC from list.'
ROW= 4,COLUMN=11,HEIGHT=11,WIDTH=57,WINDOW=11,POPUP= 0,BORDER= 
2,HEADLEN=55,
RETURN=0
MULTI=0
HEADING='Select the request you want to execute and press ENTER:'
DATA='   '
GOTO='        ',VALUE='* FOCEXEC'
$
DISPLAY=BORDER,$
HIDE=BANNER,$
HIDE=MAIN,$
HIDE=EXECTYPE,$

Compiling the Transfer File

How to:

Compile a Transfer File

The transfer file can be executed in its current format, but it may execute slowly, and uses a large amount of memory. You can make your window application more efficient, requiring less time and memory for execution, by compiling it.

You can compile a transfer file using the WINDOW COMPILE command. This produces a new compiled window file, in the same format as the window files produced by Window Painter.

Note that before you can issue this command, a PDS with LRECL 4096 and RECFM F must have already been allocated to ddname FMU. However, you do not need to create this PDS if you are only going to use the transfer file during the current FOCUS session: Window Painter temporarily allocates the PDS.

Top of page

Syntax: How to Compile a Transfer File

WINDOW COMPILE windowfile

where:

windowfile

Is the name of the transfer file.

This must be a member name of a member of a PDS allocated to ddname TRF.

The command creates a new member of the PDS allocated to ddname FMU, with the same member name specified in the command.

When a Dialogue Manager -WINDOW command is encountered in a FOCEXEC, FOCUS searchs for a compiled window file (an FMU file) with the specified file name. If the compiled file is not found, the transfer file (TRF file) with the same file name is used.

Note that if you compile a transfer file and later make changes to it, you need to recompile the updated transfer file: otherwise, FOCUS continues to use the older, unchanged compiled file.