2003,

J.Cody

Modifying PB/DOS Applications to Achieve Compatibility with All Windows Versions

By all Windows versions, we mean Windows 95, 98, ME, NT4, 2000, and XP. By compatibility, we mean the ability to successfully install and run a common set of PB/DOS executables in all Windows versions. Who is this for? This document will help anyone who contemplates modifying a PB/DOS application so that it installs and runs in all versions of Windows. About XP: contrary to popular myth, Windows XP is the most stable and flexible platform for PB/DOS applications. When the extended functionality of Cmd.Exe is combined with all of the XP scripting options, a PB/DOS application can perform a myriad of functions that are far beyond the reach of Command.Com and DOS batch (.BAT) files. You may use the Acrobat Reader <Text Select Tool> to highlight and copy Internet links, source code, and other portions of this document. This document, and portions thereof, may be freely distributed without modification.

Feasibility
If your client can economically justify migration to PowerBASIC Windows compilers, convert or re-write the application as a Windows development project. Otherwise, insist on a feasibility study with intensive client participation. Because legacy stuff falls off the radar screen when technology upgrades are frequent, you must verify that it is feasible to gather the prerequisite components for an application maintenance project. The work product of this study is to reconstruct the application development environment including PowerBASIC software, client source code, and third-party software. The search for components should include all applicable software purchase/license agreements. These agreements may enable you to re-acquire missing components from commercial vendors, from shareware authors, and from PowerBASIC.

PB/DOS Source Code Inventory

Take an inventory of the application source code to determine whether all native PB source files exist or can be retrieved from archival storage. Search PB source files for $INCLUDE references, including all nested levels of PB source code files (i.e., BAS, INC, BI, etc.).

2003,

J.Cody

External Tools Inventory

Take an inventory of the application source code to identify all external tools that are bound into the application. In the heyday of PB/DOS, most big commercial applications consisted of PB source code augmented by numerous third-party tools and toolboxes. Search for $LINK references to object (OBJ) files, unit (PBU) files, and library (PBL) files in all nested levels of source files developed by the client or provided by software vendors.

Project Scope and Cost

During the feasibility study, you can evaluate many issues that will determine the scope and cost of achieving universal Windows compatibility. As you examine the application and re-construct the development environment, you should consider the following compatibility topics and issues: DOS/Windows myths and facts. Equipment and configuration functions. Audio functions. Task management. Reporting/printing functions.

As we discuss compatibility issues, we realize that almost anything is possible without constraints on time or cost. However, within this document, we will assume that time and cost are major constraints; otherwise, it would be pointless to consider extending the life of a PB/DOS legacy application

About Our Compatibility Project

The PB/DOS application that we modified for universal compatibility consisted of ten executables compiled from over 60,000 PB/DOS source statements. The following external toolboxes were also linked into these ten PB/DOS programs: PB/Vision, QuickPak Pro for PowerBASIC, and UltraShell. In addition, all of the programs used specific tools from other PB/DOS toolboxes plus homegrown object (OBJ) modules compiled by the freeware A86 Macro Assembler (a nice DOS tool that we wish we knew about in 1990). Our project was economically justified by projected reductions to customer service costs. The PB/DOS application had been introduced in 1993. In recent years, it was distributed via the Internet for use by subscribers to the clients popular database products. All database subscribers are entitled to free customer service via 800-number consultations. Although the PB/DOS application was still favorably received by users, the clients customer service costs escalated every time Microsoft released a new version of Windows. As the client put it, those geeks in Redmond have created a support nightmare!

2003,

J.Cody

Survey of Compatibility Issues

Strictly for cosmetic purposes, some PB/DOS applications used graphics to build splash screens during startup. To ensure compatibility, and also because these old DOS splash screens look rather silly today, you should remove or disable these graphics mode startup routines. Furthermore, removal of VESA graphics is a compatibility mandate rather than a recommendation. We will not attempt to resolve compatibility issues for PB/DOS applications where application functionality actually depends upon graphics mode video or data communications. For these uncommon requirements, we will assume that you will do your own research or simply remove these functions from the application.

DOS/Windows Myths and Facts

Myths about DOS support are spawned whenever a new version of Windows is released. However, myth makers spun out of control when Win XP was introduced. In reality, Win XP is probably the platform of choice for PB/DOS applications after they have been made universally compatible with Windows. The vast majority of the low level functions and performance tricks embedded in PB/DOS tools and toolboxes were written to conform to specifications for DOS Version 5.0. Therefore, if Win 95 and Win NT4 are your floor levels for compatibility, many of these handy tools are compatible with most versions of Windows. However, to achieve universal Windows compatibility, you must limit usage to tools that are universally supported by Windows. For professional grade PB/DOS tools and toolboxes, you should expect that all versions of Windows will support: Text-mode video accelerators that write/read mapped DOS memory. DOS mouse tools. DOS drive/folder/file tools (using short names in 8.3 format). DOS Exec (INT 21H, Function 4BH) tools for task management. DOS XMS memory management. As we shall explain later, universal compatibility for SHELL statements and DOS Exec tools is easy to achieve by modifying these functions to always invoke the appropriate command interpreter (Command.Com or Cmd.Exe) and to always invoke Start as a command rather than as a program (i.e., Start rather than Start.Exe). PB/DOS tools for Extended Memory (XMS) and Expanded Memory (EMS) are configuration issues rather than compatibility issues. You can request either or both of XMS and EMS memory in application PIF files, and your PB/DOS

2003,

J.Cody

application can determine if XMS and/or EMS are accessible via API functions provided by toolboxes that support XMS/EMS. However, configuration issues for some Windows versions make it challenging for non-technical users to ensure that EMS will be an available option in VDM/NTVDM environments. Since toolbox API syntax for XMS and EMS functions are very similar, you should convert all EMS functions to XMS functions because it is relatively easy for users to ensure that XMS is an available option in VDM/NTVDM environments. If you convert all EMS functions to XMS functions, you should also disable EMS in the PIF file(s) that you install with the application. By doing this, you will elude some setup issues for Win ME. As you will see when we subsequently discuss installation tactics, installing appropriate PIF files is a simple but important requirement. When you consider what we have discussed so far, it should be evident that most of the truly useful functions offered by PB/DOS tools and toolboxes do not inhibit Windows compatibility.

Equipment and Configuration Functions

One PB/DOS tool that is universally meaningful is a Program Segment Prefix (PSP) access function that returns a fully qualified <homepath> for DOS executables. In most applications, finding <homepath> is one of the first program initialization tasks. If you are working with a commercial grade PB/DOS application, a PSP tool (based on INT 21H, Function 62H) should already be present, but an equivalent function written in PB source code is presented later in this document. For other system issues, many of the old PB/DOS tools for surveying hardware and software configurations are executable but no longer very meaningful because of new hardware technology and Windows version idiosyncrasies. PB/DOS applications generally used a mixture of PB run-time variables and toolbox functions to survey the operating environment with respect to storage device types, video adapters, printer ports, and software versions for DOS and Windows. The easy way to deal with system requirement issues is to move them into a modern Windows install program and let the install program verify your application system requirements. Let the install program restrict your installs to Win 95, 98, ME, NT4, 2000, and XP. By default, this implies floor level support for DOS Version 5.0 and VGA video. If needed, you can direct most installers to verify numerous other system attributes besides Windows version.

2003,

J.Cody

Since cost is an issue, be aware that our recommended Windows Installer costs less than $50 and is more suitable for PB/DOS installs than other popular installers in the $300-$1200 price range. These price quotations are as of 2003. We will subsequently discuss installation tactics. In your PB/DOS application, simply plan to remove tools that verify Windows versions, DOS versions, and video support. In most cases, these functions still execute but are no longer meaningful due to Windows version idiosyncrasies. We will subsequently discuss reporting/printing issues, but we can point out here that you should plan to remove all PB/DOS configuration tests for printers. As you will learn, the best way to deal with reporting and printing is to use the Windows Default Printer. The most vexing equipment/configuration issue concerns functions that attempt to identify mass storage drive types. The problem here is that media codes and other attributes for devices such as writable CD and DVD drives are not defined for the DOS INT functions that are used to interrogate device types. Thus, when PB/DOS tools are used to find a disk drive, Windows version idiosyncrasies diminish the credibility of these tools. Using the same PB/DOS tools, you will get results that vary by Windows version. In Win XP Pro, for example, your PD/DOS tools may report that writable CD/DVD drives are available for use as fixed disk drives. To resolve this issue, we wrote a simple PB source code function which verifies that a drive is write-enabled and formatted for use as a FAT16/FAT32/NTFS drive. This function is presented later in this document.

Audio Functions
PB background audio statements often produce results quite different from their intended sound effects in Windows NTVDM environments (i.e., NT4/2000/XP). You should consider removing PB SOUND and PLAY statements from your application. We also removed BEEP statements because, on many systems, BEEP (i.e., bell tone) sounds like a chirp of approval rather than a warning or error alert.

Task Management
By task management, we mean all application functions launched by PB SHELL statements or by DOS Exec tools such as the UltraShell toolbox or the LoadExec tool in QuickPak Pro for PowerBASIC. These application functions may include: Execute DOS commands. Execute batch files (BAT files or other script files). Launch DOS programs. Launch Windows programs. Launch Windows file association actions.

2003,

J.Cody

Like many commercial PB/DOS applications, the one that we modified made extensive use of PB SHELL, UltraShell, and the QuickPak LoadExec tool. We did NOT have to deal with PB CHAIN, and we offer no compatibility advice about CHAIN. SHELL statements and PB/DOS Exec tools present two compatibility issues: 1. What works in one Windows version may fail in other versions. 2. What works in all Windows versions may produce results that vary by version. Most PB/DOS programs require modification to ensure that SHELL statements and PB/DOS Exec functions work in all Windows versions and produce the same results in all Windows versions. Universal Compatibility Guidelines for Task Management PB/DOS programs must explicitly invoke the proper command interpreter to ensure that many task management functions are universally compatible. For Win 95/98/ME, the proper command interpreter is Commamd.Com. For Win NT/2000/XP, the proper command interpreter is Cmd.Exe. By convention, always use <Start> to launch Windows file association actions and Windows executables (because <Start> options offer extended process control features). When PB SHELL statements are used, PB/DOS programs must explicitly invoke the proper command interpreter for all task management functions except launching DOS executables (EXE and COM). When PB/DOS Exec tools are used, PB/DOS programs must explicitly invoke the proper command interpreter for all task management functions except launching DOS executables (EXE and COM). To use Start, you must always invoke the proper command interpreter and invoke <Start> as opposed to <Start.Exe>. If you need to guarantee the functionality of the Start wait option (/w), you must invoke Start from a script (e.g., a .BAT file). Identification of Proper Command Interpreter While PB/DOS programs can rely on the presence of environment variable <comspec>, programs cannot trust that <comspec> will always identify the proper command interpreter. For example, if you examine <comspec> from the NT Command Prompt in Win NT4/2000/XP, <comspec> will identify Cmd.Exe. However, if you examine <comspec> from a PB/DOS program, <comspec> will identify Command.Com, which is not the proper command interpreter for many task management functions in Win NT4/2000/XP. We used the following PB function to ensure that programs were able to identify and use the proper command interpreter for task management procedures.

2003,

J.Cody

%ISufferFromOCD=-1 'True/False FUNCTION IsComspecValid% (SEG Cspec$) LOCAL PUBLIC 'Function returns True (-1) if it can set Cspec$ to fully qualified path 'for Command.Com or Cmd.Exe (in 8.3 format). Cmd.Exe is automatically 'adopted when it exists with Command.Com (Win NT4/2000/XP). LOCAL x$,y$ Cspec$= 'Reset path x$=ENVIRON$(COMSPEC) IF LEN(x$)<1 THEN x$=ENVIRON$(ComSpec) $IF %ISufferFromOCD IF LEN(x$)<1 THEN x$=ENVIRON$(Comspec) IF LEN(x$)<1 THEN x$=ENVIRON$(comSpec) IF LEN(x$)<1 THEN x$=ENVIRON$(comspec) $ENDIF IF LEN(x$)<1 THEN EXIT FUNCTION x$=UCASE$(x$) IF RIGHT$(x$,12)=\COMMAND.COM THEN y$=EXTRACT$(x$,COMMAND.COM)+ CMD.EXE IF DIR$(y$)<> THEN x$=y$ ELSEIF RIGHT$(x$,8)<>\CMD.EXE THEN EXIT FUNCTION END IF IF DIR$(x$)<> THEN Cspec$=x$ IsComspecValid%=-1 END IF END FUNCTION

Function <IsComspecValid%> does NOT require awareness of current Windows version. Based on widespread deployment experience, here are the only known caveats for using function <IsComspecValid%>:
A tiny population of power users may utilize third-party command interpreters such as 4DOS for Windows. Users of Win 2000 Servers sometimes move Cmd.Exe out of its installed location as a security precaution (as per an old MS KB issue for 2000 Servers). We found no evidence of this with workstation versions of Windows.

When the proper command interpreter (i.e., Cspec$) is used in conjunction with our universal compatibility guidelines, PB/DOS programs can execute task management functions without regard to what version of Windows is currently running.

PB Shell Examples
In the following examples, variable Cspec$ is always set to the fully qualified path for the proper command interpreter (e.g., C:\WINDOWS\COMMAND.COM or C:\WINNT\SYSTEM32\CMD.EXE). Bad Examples: Not Universally Compatible
SHELL VER >C:\MYFOLDER\WINVER.TXT SHELL START http://www.yahoo.com/

2003,

J.Cody

SHELL SHELL SHELL SHELL

START.EXE C:\MYFOLDER\PGMDOCS.PDF START C:\MYFOLDER\MYWINPGM.EXE [params] START.EXE C:\MYFOLDER\MYWINPGM.EXE [params] C:\MYFOLDER\MYDOSBAT.BAT [params]

'Win Exe 'Win Exe 'BAT

Many SHELL statements require explicit specification of the proper command interpreter to achieve universal compatibility. Otherwise, SHELLed functions may fail to execute or produce results that vary by Windows version. This is true even for the SHELL VER command, as shown above, which always returns Windows version only when modified as shown below. All of the SHELL Start commands, as shown above, will fail to execute in specific versions of Windows, but all Start commands will execute when modified as shown below. Likewise, SHELL for a batch file, as shown above, is not universally compatible unless modified as shown below.

Good Examples: Universally Compatible

SHELL SHELL SHELL SHELL SHELL SHELL Cspec$ + /CVER >C:\MYFOLDER\WINVER.TXT Cspec$ + /CSTART http://www.yahoo.com/ Cspec$ + /CSTART C:\MYFOLDER\MYPGMDOC.PDF Cspec$ + /CSTART C:\MYFOLDER\MYWINPGM.EXE [params] Cspec$ + /CC:\MYFOLDER\MYDOSBAT.BAT [params] C:\MYFOLDER\MYDOSPGM.EXE [params]

'Win Exe 'BAT 'DOS Exe

Universal compatibility for SHELL statements often implies redundant invocations of command interpreters, which reduces available DOS memory by 5kb to 8kb while the target function is active. As noted below, we elected to exclusively use toolbox EXEC functions in lieu of SHELL statements.

PB/DOS Exec Tools

Because they were available, we used PB/DOS Exec (INT 21H, Function 4BH) tools for all task management functions. The advantage offered by QuickPak LoadExec is that LoadExec circumvents one level of command interpreter redundancy and will also retrieve the exit code from child processes. The UltraShell toolbox provides the features of LoadExec but also offers memory swapping, which dramatically increases the amount of conventional memory that is available to child processes. As shown below, PB/DOS Exec tools must explicitly invoke the proper command interpreter to launch universally compatible DOS commands, Windows file association actions, Windows executables, and script or batch (BAT) files. PB/DOS Exec Tool Examples (for LoadExec and UltraShell)
Fully Qualified Path Cspec$ Cspec$ Cspec$ Cspec$ Cspec$ C:\MYFOLDER\MYDOSPGM.EXE C:\MYPATH\PKZIP.EXE C:\MYPATH\PKUNZIP.EXE Parameters /CVER >C:\MYFOLDER\WVER.TXT /CSTART http://www.yahoo.com/ /CSTART C:\MYFOLDER\MYPGMDOC.PDF /CSTART C:\MYFOLDER\MYWINPGM.EXE [params] /CC:\MYFOLDER\MYDOSBAT.BAT [params] [params] [params] [params]

2003,

J.Cody

As a reminder, we note again that in order to guarantee the functionality of the Start wait option (/w), you must invoke Start from a script (e.g., a .BAT file). When one PB/DOS program invokes another DOS program, both QuickPak and UltraShell can retrieve error codes set by the child program: (1) as set in PB/DOS child programs via statement <END [code]>, or (2) as set by DOS utilities such as PKZIP/PKUNZIP. This is a very useful feature that enables parent programs to recognize exceptions and errors reported by child programs. With UltraShell, the elegant feature is memory swapping, which reduces the memory footprint of the parent program down to less than 5kb before the child process is invoked. Therefore, a PB/DOS program can invoke very large DOS child processes with UltraShell. For reasons stated earlier, we used the UltraShell API to restrict memory swapping media to XMS and disk (by disabling EMS as a memory swapping option).

Reporting/Printing Functions
This commonplace application requirement is probably the most frequently queried DOS compatibility issue at Internet support sites for Windows and thirdparty software products. For PB/DOS applications, this issue can be resolved by using the techniques described below.
Printing Reports to the Windows Default Printer

In a PB/DOS application, low-level printing issues are eluded by diverting report output to disk. All occurrences of printer output functions are replaced by disk output (or append) functions. After one or more report files are created, background printing is accomplished by launching PrintFile, the award-winning freeware utility by Peter Lerup, http://www.lerup.com/printfile/. PrintFile is compatible with Windows 95, 98, ME, NT4, 2000, and XP. While PrintFile offers many advanced features, only basic setup options are needed to spool report files to the Windows Default Printer, which may be any printer interface or device supported by Windows. For our PB/DOS application, we obtained Peter Lerups permission to distribute PrintFile as part of our Windows install package. We understand that others have likewise been granted PrintFile distribution rights. Like most freeware authors, Lerup reserves all rights to his product and prohibits fee-based or for-profit distributions. Instructions for configuring, installing, and using PrintFile are presented later in this document. We used only basic PrintFile features to achieve universal Windows compatibility. To learn how others have implemented the advanced features of PrintFile, we refer you to a web site that may be the most comprehensive source of methods for resolving DOS compatibility issues for reporting/printing:

2003,

J.Cody

http://www.columbia.edu/~em36/wpdos/index.html. Also see the related web page at http://www.columbia.edu/~em36/wpdos/windowsxp.html. This Internet site supports a devoted cult of WordPerfect For DOS Users. Many academics and professional writers insist that the features and productivity offered by the final two major versions of WordPerfect For DOS have never been duplicated or surpassed in any Windows word-processing product (even though all the king's men continue to labor in Redmond). This WP/DOS cult publishes methods and cites tools that enable them to produce elegant documents that preserve the complex formatting options offered by WP/DOS. Several methods for using PrintFile in conjunction with special report formatting tools are published at this WP/DOS site.
Report Formatting Tactics

Like many PB/DOS applications, the one that we modified used PB source code to format printer-ready report streams for 80-column and 132-column reports. We diverted these report streams to disk by creating disk print files (*.PRN). Furthermore, our PB/DOS application enabled users to dynamically configure the application to use one of three generic report formatting methods: Hewlett Packard Printer Control Language (PCL). Epson (Matrix) printer control strings. Xerox (Diablo Wheel) printer control strings. For each formatting option, the application used only control strings defined in the manufacturers base level specifications. As a result, the application was able to support virtually all popular printers. One rarely encountered exception is GDI-Only printers (a.k.a. Windows-Only printers in some literature, or a.k.a. devil devices by Linux programmers and most printer manufacturers). The vast majority of non-impact printers are compatible with HP PCL (e.g., printers that use laser, inkjet, LED, or copy/fax-machine technologies). Moreover, many new GDI printers offer GDI (Windows graphics device interface) compatibility as a control option rather than as a requirement. In such cases, HP PCL is also supported. Six (6) basic printer control strings that may be used to format most 80-column and 132-column reports are described later in this document. In some PB/DOS applications, you may find that report formatting and printing is handled by a PB/DOS toolbox. Several toolboxes offered report production tools. In these toolboxes, the degree of sophistication may extend to user setup and report option dialogs, support for printer control languages that are still effective (because they are a subset of the extended languages used by new printer models), and the ability to rename or create device definitions for cosmetic purposes (e.g., so that users can select Non-Impact Printers instead of something as dated as LaserJet Model I). Such toolboxes would enable

10

2003,

J.Cody

users to select a device that is compatible with their current Windows Default Printer. After device selection setup, the toolbox should be able to emit a device-specific-printer-ready report stream in response to your deviceindependent calls to the toolbox API. The deal breaker for this approach is redirection. You must be able to configure the toolbox so that it always creates disk files and never tries to access a printer device. To reach beyond the formatting tactics that we have discussed, we again refer you the WP/DOS web site http://www.columbia.edu/~em36/wpdos/index.html where you may find a compatibility solution that satisfies your report formatting requirements. Search this site for references to PrintFile, Ghostscript, and RoPS to find descriptions of report formatting tactics.

PB Source Code Functions and Examples

FUNCTION GetMyProgramSpec$ LOCAL PUBLIC 'Gets fully qualified path to executing program 'Returns <driveletter>:\<path>\<filespec> 'Example: C:\MYAPP\MYPGM.EXE 'Returns null string if ProgramSpec is invalid (8.3 format) LOCAL Myps%,Myps$ REG 1,&H6200 CALL INTERRUPT &H21 'Get PSP addr DEF SEG=REG(2) 'Seg=PSP DEF SEG=PEEKI(&H002C) 'Seg=environ block DO UNTIL PEEKI(Myps%)=0 'Find repeated asciiz delim INCR Myps% LOOP Myps$=PEEK$(Myps%+4,127)+CHR$(0) 'Max filespec + safety delim DEF SEG Myps$=UCASE$(LEFT$(Myps$,INSTR(1,Myps$,CHR$(0))-1)) IF DIR$(Myps$)<> THEN GetMyProgramSpec$=Myps$ END FUNCTION FUNCTION GetMyHomePath$ LOCAL PUBLIC 'Gets path to folder for executing program 'Returns path plus trailing backslash if no error 'Example: C:\MYAPP\ LOCAL x$,x%,y$ x$=GetMyProgramSpec$ DO x%=INSTR(1,x$,\) 'Scan for backslash y$=y$+LEFT$(x$,x%) 'NOP in final iteration x$=RIGHT$(x$,LEN(x$)-x%) 'NOP in final iteration LOOP WHILE x% GetMyHomePath$=y$ END FUNCTION FUNCTION IsWritableDrive% (SEG Drivespec$) LOCAL PUBLIC 'Verifies whether a drive is FAT16/FAT32/NTFS write-enabled. 'CD/DVD and unformatted drives fail this test (which is our purpose). 'Drivespec$ may be driveletter, drive-id, or absolute path:

11

2003,

J.Cody

'(1) Only first character of Drivespec$ is inspected. '(2) Drivespec$ examples: a, B, c:, D:\, e:\myapp, F:\MYAPP\MYPGM.INI 'Function returns True (-1) only if drive is write-enabled. LOCAL Dltr$,Dtime&,Dspec$,Dhdnl%,Derr% Dltr$=UCASE$(LEFT$(Drivespec$,1)) IF Dltr$<A OR Dltr$>Z THEN EXIT FUNCTION Dtime&=TIMER+86400 DO 'Find non-existent filename Dspec$=Dltr$+:\D$+LTRIM$(USING$(######,Dtime&))+.$$$ INCR Dtime& LOOP UNTIL DIR$(Dspec$,6)= Dhndl%=FREEFILE ERR=0 ON LOCAL ERROR RESUME NEXT 'Use local error handling OPEN Dspec$ FOR BINARY ACCESS READ WRITE AS Dhndl% Derr%=ERR CLOSE Dhndl% ON LOCAL ERROR GOTO 0 'Revert to global error handling ERR=0 IF Derr% THEN EXIT FUNCTION KILL Dspec$ IsWritableDrive%=-1 'Drive is write-enabled END FUNCTION 'SOME USEFUL STRINGS FOR REPORT FORMATTING 'Six generic printer control strings (from base level specifications) 'for PCL printers, matrix printers, and wheel printers. DIM Hp80 AS SHARED STRING 'HP PCL 80-col setup DIM Hp132 AS SHARED STRING 'HP PCL 132-col setup DIM Em80 AS SHARED STRING 'Epson/Matrix 80-col setup DIM Em132 AS SHARED STRING 'Epson/Matrix 132-col setup DIM Xd80 AS SHARED STRING 'Xerox/Diablo 80-col setup DIM Xd132 AS SHARED STRING 'Xerox/Diablo 132-col setup 'Zero (0) and uppercase letter (O) may look alike in some fonts ' One (1) and lowercase letter (l) may look alike in some fonts Hp80=CHR$(27)+&l0O+CHR$(27)+(10U+CHR$(27)+(s0p10h12v0s0b3T Hp132=CHR$(27)+&l0O+CHR$(27)+(10U+CHR$(27)+(s0p16.67h8.5v0s0b0T Em80=CHR$(27)+P+CHR$(18) Em132=CHR$(27)+P+CHR$(27)+CHR$(15) Xd80=CHR$(27)+Q+CHR$(27)+CHR$(31)+CHR$(13) Xd132=CHR$(27)+Q+CHR$(27)+CHR$(31)+CHR$(9) 'SOME USEFUL COMPATIBILITY SUPPORT VARIABLES DIM Homepath AS SHARED STRING 'Path+backslash for executing program 'PrintFile variables used to print report files to Windows Default Printer DIM Prfile32exe AS SHARED STRING 'Installed PrintFile executable DIM Prfile32hlp AS SHARED STRING 'Installed PrintFile help DIM P32original AS SHARED STRING 'Installed version of PRFILE.INI DIM Prfile32ini AS SHARED STRING 'Dynamic INI file PRFILE.INI DIM P32startbat AS SHARED STRING 'Dynamic batch file P32START.BAT DIM P32filelist AS SHARED STRING 'Dynamic report list file PRLIST.$$$ DIM P32startup AS SHARED STRING 'Command line syntax for P32START.BAT 'Set working directory for the PB/DOS program that is executing. Homepath=GetMyHomePath$ 'See function.

12

2003,

J.Cody

IF LEN(Homepath)<1 THEN ERROR 100 'Call error handler with error code 100 CHDRIVE LEFT$(Homepath,2) 'Must precede CHDIR for compatibility CHDIR LEFT$(Homepath,LEN(Homepath)-1) FUNCTION IsPrintFileTaskReady% LOCAL PUBLIC 'For use as run-once PB/DOS program initialization procedure. 'Returns True (-1) if PrintFile is available and properly initialized. '(1) Verifies all PrintFile components. '(2) Initializes PrintFile variables used to print report files to ' Windows Default Printer. '(3) Refreshes files PRFILE.INI and P32START.BAT. LOCAL Phdl%,Lini&,Tini$ IF LEN(Homepath)<1 THEN EXIT FUNCTION 'Program not properly initialized Prfile32exe=Homepath+PRFILE32.EXE 'Installed PrintFile executable Prfile32hlp=Homepath+PRFILE.HLP 'Installed PrintFile help P32original=Homepath+PRFILE.ORG 'Installed version of PRFILE.INI Prfile32ini=Homepath+PRFILE.INI 'Dynamic INI copy of PRFILE.ORG P32startbat=Homepath+P32START.BAT 'Bat file will start PrintFile P32filelist=Homepath+PRLIST.$$$ 'Text file will list report files 'Build batch file command syntax for PrintFile startup: '/w wait option ensures Win spooler gets stuffed before parent program ' regains control, because parent may want to delete report file(s). '/q quiet-then-quit option runs Prfile32 as hidden task that quits after ' all report files are processed (spooled). '/i INI option specifies temp INI file created from installed ORG file. '@P32filelist specifies temp file that lists report file(s) to be printed. P32startup=@START /w +Prfile32exe+ /q /i:+Prfile32ini+ @+P32filelist IF DIR$(Prfile32exe)= OR DIR$( Prfile32hlp)= OR _ DIR$(P32original)= THEN EXIT FUNCTION IF DIR$(Prfile32ini)<> THEN KILL Prfile32ini IF DIR$(P32startbat)<> THEN KILL P32startbat Phdl%=FREEFILE OPEN P32original FOR BINARY ACCESS READ AS Phdl% Lini&=LOF(Phdl%) 'You could add test here to verify length matches installed length GET$ Phdl%,Lini&,Tini$ CLOSE Phdl% Phdl%=FREEFILE OPEN Prfile32ini FOR BINARY ACCESS WRITE AS Phdl% PUT$ Phdl%,Tini$ CLOSE Phdl% Phdl%=FREEFILE OPEN P32startbat FOR OUTPUT ACCESS WRITE AS Phdl% PRINT #Phdl%,P32startup CLOSE Phdl% IsPrintFileTaskReady%=-1 END FUNCTION

PrintFile Deployment
The primary references for PrintFile are http://www.lerup.com/printfile/ and the comprehensive PrintFile Help system. The instructions that we present here explain how to prepare PrintFile for installation as an integral part of a PB/DOS

13

2003,

J.Cody

application package. These instructions assume that you will use PrintFile to print formatted report files to the Windows Default Printer. We recommend that you follow these instructions before you actually install PrintFile for use as a general utility on your PC.

Save Three PrintFile Components

The downloadable package for PrintFile is PRFxxx.ZIP where xxx is version number (e.g., PRF215.ZIP for version 2.1.5). You must save a copy of this ZIP file for subsequent distribution with your PB/DOS application (as per distribution requirements specified by the author). Create a folder (e.g., PBDOSP32), then copy PRFxxx.ZIP into folder PBDOSP32. From the ZIP file, extract files PRFILE32.EXE and PRFILE.HLP into folder PBDOSP32.

Make File Prfile.Org

Run <\PBDOSP32\PRFILE32.EXE>. Your purpose is to create file PRFILE.INI, which you will rename as PRFILE.ORG and save for use by your PB/DOS application.

Select <Settings>

14

2003,

J.Cody

Enable/Disable settings as shown above Select <Text file>

Enable/Disable settings as shown above Select <Ok>

15

2003,

J.Cody

Select <Save> to create Prfile.Ini

Select <Exit>.

By default, PRFILE.INI is created in your Windows folder (e.g., C:\Windows or C:\WINNT). 1. Find PRFILE.INI (and verify by file date/time that you just created it). 2. Rename PRFILE.INI as PRFILE.ORG 3. Move PRFILE.ORG into folder PBDOSP32.

Verify Four PrintFile Components for PB/DOS Applications

The contents of file PRFILE.ORG should resemble:
[General] Version=2.1.5 [Settings List]

16

2003,

J.Cody

Default settings=1 [Default settings] EnableTextPrint=0 QuitFromComLine=1

Folder PBDOSP32 should contain four files: 1. PRFxxx.ZIP 2. PRFILE32.EXE 3. PRFILE.HLP 4. PRFILE.ORG These are the four files that should be included when you build a PB/DOS application install package.

How to Install PrintFile for Use as a General Utility

To install PrintFile on your PC for use as a general utility, extract all files from your downloaded copy of PRFxxx.ZIP into a temporary folder, and then follow instructions in file README.TXT.

How to Use PrintFile in Your PB/DOS Application

To use or test PrintFile in your PB/DOS application, copy the four files from folder PBDOSP32 into the folder that contains your PB/DOS executables. Note that your PB/DOS programs will NOT use the PrintFile components that you may have installed on your PC for use as a general utility. Listed below are the procedural steps for testing/using PrintFile from within a PB/DOS program. These procedures assume that you have modified your PB/DOS program in accordance with the compatibility guidelines presented in this document. Initialize Program for Windows Compatibility Use <IsComspecValid%> to verify and adopt the proper command interpreter (i.e., to set Cspec$ variable). Use <GetMyHomePath$> to set Homepath variable. Set working directory to Homepath directory (as per example code). Use <IsPrintFileTaskReady%> to initialize variables and to verify/refresh PrintFile components. Create Report File(s) Recommended report filespec pattern is <Homepath+<filename>.PRN> so that the working directory can readily be searched for report files. Create one or more formatted report files (i.e., divert reports to disk). Print Report File(s) Delete file P32filelist if it exists.

17

2003,

J.Cody

Create file P32filelist as a text file that lists the fully qualified path for each report file. You should verify existence of each report filespec that is listed in P32filelist. List one report file per line in P32filelist. Use SHELL or a PB/DOS Exec tool to launch PrintFile, as shown below.
'Shell method SHELL Cspec$ + /C+P32startbat 'QuickPak Pro (Exec) TaskExitCode%=LoadExec%(Cspec$,/C+P32startbat) 'UltraShell (Swap-out/Exec/Swap-in) 'See UltraShell documentation for API setup requirements/options IF Etshelloverride%(Cspec$,/C+P32startbat) THEN ERROR 199 'Call error handler ELSE SHELL END IF Ultrastatus%=EtShellStatus%(TaskExitCode%) 'See UltraShell documentation for explanation of EtshellStatus%

PrintFile Usage Characteristics

Prfile32 is started and executes as hidden task (no PrintFile dialog). Windows Print dialog pops to let user verify/change default settings. Prfile32 quits after last report file has been processed (i.e., spooled). PD/DOS program is reinstated. If program was running in full-screen mode, user may click on Taskbar icon to restore full-screen mode. PB/DOS program may immediately delete any/all report filespecs that were passed to Prfile32.

In the PB/DOS application that we modified, Prfile32 spools reports so rapidly that it is virtually transparent to the application user even though it is invoked with the Start wait option (/w).

PB/Vision Considerations
All of the programs in our PB/DOS project used the PB/Vision toolbox and the user interface resource files created by PB/Vision Workshop. The following notes are based on widespread deployment experience.

Screen Lines
PB/Vision and PB/Vision Workshop options for 25, 30, 43, and 50 lines per screen work fine in all Windows versions. However, the option for 28 lines per screen should be avoided because of VGA hardware issues. No other issues exist for screen lines in full-screen mode.

18

2003,

J.Cody

When PB/Vision is used inside a VDM/NTVDM window, all versions of Windows will automatically resize the VDM/NTVDM window as the application switches between 25, 30, 43, and 50 lines per screen. However, Windows screen resolutions of 1024 by 768 (or higher) are recommended if programs use 50 lines per screen mode because some versions of Windows allow the Taskbar to obscure the bottom border of the VDM/NTVDM window when programs switch to 50 lines per screen. Windows will provide a vertical scroll bar for partially obscured VDM/NTVDM windows, but this is not a convenient way for users to deal with lines-per-screen anomalies.

Screen Modes
PB/Vision screen modes <standard text> and <pseudo-graphics> work fine when applications run in full-screen mode. Both the arrow-style and the block-style mouse cursors work fine in full-screen mode. However, all versions of Windows will corrupt mouse control and video appearance if PB/Vision <pseudo-graphics> mode is used inside a VDM/NTVDM window. Thus, if programs are allowed to run inside VDM/NTVDM windows, <standard text> mode and the block-style mouse cursor should be used.

Mouse Support
Restrict mouse cursor to block-style if programs will be allowed to run inside a VDM/NTVDM window. No restrictions for full-screen mode.

Drag and Drop PB/Vision Windows

PB/Vision windows with drag and drop enabled work in full-screen mode and in VDM/NTVDM windows. However, when programs are run in VDM/NTVDM windows, most versions of Windows allow users to drag and drop PB/Vision windows beneath the lower bound of the current VDM/NTVDM window (such that the user cannot drag the PB/Vision window back into view). For standard PB/Vision windows, this anomaly can be defeated via PB/Vision API functions, but no such remedy is available for PB/Vision <Help> windows. Therefore, drag and drop for <Help> should be disabled in the TYPE control block for PB/Vision <Help> if programs are allowed to run in VDM/NTVDM windows.

Safe Mode for Running PB/Vision Programs in VDM/NTVDM Windows

Because of anomalies discussed above, we recommend a Safe Mode tactic for allowing users to run PB/Vision programs inside VDM/NTVDM windows. Always designate Full-Screen mode in program PIF files. Enable run-in-window mode only by enabling keys Alt+Esc and Alt+Enter in program PIF files. This PIF configuration tactic enables users to switch back and forth between fullscreen and run-in-window modes. This also allows users to revert to full-screen

19

2003,

J.Cody

mode if they do not like the way Windows resizes VDM/NTVDM windows, or if they drag and drop <Help> beyond their reach in a VDM/NTVDM window. Note, however, that this safe mode tactic should be used only when programs are restricted to <standard text> screen mode and block-style mouse cursors.

Using LZEXE.EXE with UltraShell and/or PB/Vision

Freeware utility LZEXE.EXE is a popular tool that converts PowerBASIC executables into compressed self-extracting executables. If you intend to use this tool, be sure to observe the following procedural sequence: 1. Compile PB executable. 2. If you use the extended UltraShell API (USAPI.OBJ), always <ULTRASHL> it (i.e., apply it) to the executable before compression. 3. Compress the executable with LZEXE. 4. If you use a PB/Vision resource file, always <ATTACH> it to the executable after compression.

Windows Install Tactics

Proper installation is necessary in order to achieve universal Windows compatibility for PB/DOS applications. Two requirements must be satisfied: You must assemble a universally compatible install library. You must use an appropriate Windows Install product.

How to Build an Install Library

Our instructions assume that you want to build a universal install package that will enable a common install executable to perform both installs and upgrades. Most modern Windows Install products support this approach. As a result, your install/upgrade package will consist of a single self-extracting executable that can be distributed via the Internet or via CD media. Create two folders named <MODFILES> and <ALLUSERS>. Populate <MODFILES> with copies of the following application files: Excluding PIF files, all modifiable application files. These are file types that may be modified when the application runs. Examples are INI files, CFG files, data files, and other modifiable files that are not automatically created by the application (if the file is found to be missing). Files in <MODFILES> will be installed only when they do not already exist. If installed users need to perform a clean install, your install/upgrade documentation should instruct users to completely un-install the application before running the install package.

20

2003,

J.Cody

Populate <ALLUSERS> with copies of the following application files: Current versions of all read-only files. These include all file types that are never modified by the application. Examples are EXE files, HLP files, ICO (icon) files, static batch files, etc. Current file versions for PrintFile (i.e., four files from folder PBDOSP32). Current file versions for other utility products used by your application. All PIF files created by you. Files in <ALLUSERS> are always installed and will overwrite existing copies of matching files. We include all PIF files because users may inadvertently delete shortcuts or disable desirable run-time properties such as XMS. Therefore, inclusion of all PIF files in <ALLUSERS> provides a means of restoring all original run-time properties by re-running the install package.

Roles Played by Your PIF Files and Shortcuts Created by Installers

A PIF file created by you should be installed for each executable that is a user entry point to your PB/DOS application. Many applications have only one user entry point. You do not need PIF files for application executables that are not externally launched by users. Each of your PIF files should specify the run-time properties for its corresponding executable file. Note that your PIF files are not intended for direct use as <shortcuts> to launch application executables. Your PIF files must be installed in the same folder as their corresponding executables. Never install your PIF files in Start Menus or on Desktops. User <shortcuts> to launch your application should be created by your Windows Install software. Moreover, when these launching <shortcuts> are created, they must point to your PIF files rather than to EXE or BAT files. Finally, each PIF file must point to its corresponding executable (by name only, without a path). Modern Windows Installers can create launching <shortcuts> and install them in Start Menus and on Desktops. These <shortcuts> will specify a fully qualified path to a PIF file and a fully qualified path to the working directory where the PIF file is located. <shortcuts> may also be created and installed with a fully qualified path to a suitable icon (ICO file). Icon files should ideally be installed in the same folder as PIF files and executables. Since Shortcuts created by Installers will establish working directories (startup folders), your PIF files should reference their corresponding executables by name only (i.e., by name and extension without a path). The purpose of this installation tactic is to enable one common set of PIF files to dictate application run-time properties in all Windows versions. In other words, a static set of PIF files is installed for all versions of Windows, but version-

21

2003,

J.Cody

specific <shortcuts> to these PIF files are created by your Windows Installer software. This tactic enables universal compatibility for Win 95/98/ME/NT4/2000/XP to be achieved by installing common set of PIF files in all Windows versions.

Win 95/Win 98 PIF Files

We actually borrowed a Win 95 system to create PIF files for the application that we modified for compatibility. We created Win 95 PIF files to ensure compatibility with all Windows versions (95, 98, ME, NT4, 2000, XP). If you cannot gain access to a Win 95 system, you can create Win 98 PIF files with a very high degree of compatibility assurance. We hesitate to say absolute assurance only because we did not conduct tests on pristine Win 95 or Win NT4 systems (i.e., original releases of Win 95 and Win NT4 without any updates). To avoid awkward logistics (borrowing Win 95), we eventually switched to Win 98 PIF files and have no problems to report after widespread deployment. We intend to keep our old Win 98 laptop solely for the purpose of creating PIF files. Note: if you are willing to raise your floor levels of compatibility to Windows 98SE and Windows 2000, you can create PIF files with Windows XP. If you do create Win XP PIF files, your Installer software must restrict installs to Win 98SE, ME, 2000, and XP. Win 95/98 PIF Status Considerations After you create Win 95/98 PIF files (and make backups), you can move them to a newer development platform such as Win 2000 or Win XP. However, you must exercise caution to prevent modification of your PIF files, which must be in their original state when you build your application install package. Pure copy functions are harmless, but do not open your Win 95/98 PIF files or modify their properties on your newer development platform. If you create your PIF files in accordance with our recommendations, you should not need to modify them after creation. Note that this issue disappears the instant your PIF files are installed on end-user systems (i.e., 95, 98, ME, NT4, 2000, XP). Recommended PIF run-time properties for PB/DOS executables are illustrated at the very end of this document. Here is an example of the relationship between your Win 95/98 PIF files and <shortcuts> created by the Windows Installer. Folder C:\MYAPPSYS MYDOSPGM.EXE (PB/DOS executable for scoring Tiddlywinks). MYDOSICO.ICO (Application icon).

22

2003,

J.Cody

W9XPIF01.PIF (PIF created by you).

Cmd Line: MYDOSPGM.EXE (Name only, specified by you). Working: <none>. Icon: <default> (defaults to MS-DOS icon). Font/Memory/Screen/Misc: Specified by you.

XP Desktop KeepScore (Win XP shortcut created by Installer).

Cmd Line: MYDOSPGM.EXE (Inherited from W9XPIF01.PIF). Note: Installer link target was C:\MYAPPSYS\W9XPIF01.PIF. Working: C:\MYAPPSYS (Working directory link from Installer). Icon: C:\MYAPPSYS\MYDOSICO.ICO (Icon link from Installer). Font/Memory/Screen/Misc: Inherited from W9XPIF01.PIF.

Tips for Creating a PIF File

Here is how we created our Win 95/98 PIF files for PB/DOS executables. We started by finding an MS-DOS PIF file and copying it to a working folder (e.g. PBDOSPIF). We also renamed the copied PIF file before we started modifying properties. We never gave PIF files a name that exactly matched the name of its corresponding PB/DOS executable. If we were creating a PIF for MYDOSPGM.EXE, we might name it W9XPIF01.PIF so that application users would not be tempted to launch the PIF (i.e., the PIF depends upon its launching <shortcut> to establish the working directory as the folder where the PIF and its executable are installed). For the same reason, we never assigned special icons to PIF files. We assigned application icons only to launching <shortcuts> created by the Windows Installer. We also kept a PB/DOS test executable in our PIF folder (PBDOSPIF). We renamed this test executable to correspond to the actual application program for the PIF file that we were working with. Nothing more complicated than a Hello World test program is required to work with PIF files.

Install Destination Guidelines

You should restrict install destinations for PB/DOS applications to paths that will not cause oversized (illegal) DOS (8.3-format) command expressions to be generated when your application is running. This has always been a consideration for DOS applications, but universal compatibility magnifies this issue because multiple occurrences of fully qualified paths are required for many task management functions. This means that you should not allow your Installer software to let Users choose long install paths. Instead of offering total freedom, we recommend that you

23

2003,

J.Cody

allow users to choose disk drives only. By doing this, you can restrict installs to one level above the root directory (e.g., C:\MYAPPSYS, D:\MYAPPSYS, etc). Reasonable path-length restrictions should also be enforced within the application if users are allowed to choose locations for data folders, backup folders, etc.

Windows Installer Software

Nothing that we have described so far precludes the use of most modern Windows Install products. Except for rudimentary Installers that are merely decompression tools, most Installers that are compatible with all versions of Windows can be scripted or configured to conform to the install tactics and guidelines that we have presented. Our recommended Windows Installer is the Astrum InstallWizard by Thraex Software (http://www.thraexsoftware.com/). Priced at $49 (2003), this Finnish software product is an outstanding bargain, and is ideal for PB/DOS installs. Even if you are an InstallShield expert or a Wise guru, we would recommend InstallWizard for PB/DOS applications1. InstallWizard is one of those products that must be used to be appreciated. Experience with other Installers will engender some initial skepticism because InstallWizard is such a tidy package, primarily documented by online Help. On first use, it took us about ninety minutes to generate a universal install package that worked flawlessly for our PB/DOS application. With the aid of a few tips specifically related to our previously described install tactics, you should be able to build a good install package in about twenty minutes. These tips are presented below.

Consider our strange bedfellows: a Swedish print spooler (PrintFile), a Finnish installer (InstallWizard), and a Zale compiler (PowerBASIC). This reminds us that synergy often remains hidden until you take a few steps down the path less traveled.

24

2003,

J.Cody

Sample dialog (reduced in size) illustrates how InstallWizard offers theme options (in this case, the XP Theme option). The Astrum Dialog Editor supports extensive dialog customizations.

Install projects are completed by working your way down the vertical menu of InstallWizard functions and options. A small subset of available features is needed to create a PB/DOS install package.

25

2003,

J.Cody

PB/DOS Tips for InstallWizard

General
Application Name: enter descriptive name as you want it to appear in:
Start Menu group. Control Panel <Add/Remove Software> entry. Installer dialog titles Installer dialog questions/instructions

This name sets the value of constant <AppName>, which appears as a suggested default value for many Installer settings. You can control whether and how <AppName> is used in other places. Name and Save Project Now that you have started to build an install project, select <File> and <Save Project As>. Give your project a name and save it. Afterwards, you can <Save> and <Open> your named project as needed. Company Name: sets the value of constant <Organization>. You can control whether and how <Organization> is used in other places. Version: sets the value of constant <AppVersion>. Although you must set a value, you can control whether and how <AppVersion> is used. Default Installation Path: to control and restrict installation path length, you should replace the default setting <ProgramFiles>\<AppName>. We recommend this path: <SystemDrive>:\<DosAppName>. <SystemDrive> is a built-in Installer driveletter variable (e.g., C). <DosAppName> is a user variable that you must define by selecting Use this function to <Add> and define variable vertical menu function Variables. <DosAppName>. Set the default value for <DosAppName> to a valid DOS (8.3-format) folder name (e.g., MYDOSAPP).

Default Installation Path will be C:\<DosAppName> (e.g., C:\MYDOSAPP) if you followed our recommendation. Installer variable <InstallDir> is set when you define Default Installation Path. In other Installer functions, <InstallDir> is used to reference Default Installation Path. Default Shortcut Group Name: default is <AppName>. Because path length is not an issue for Start Menu groups, <AppName> is an acceptable default (see Application Name above). For most applications, you should also enable <Use All Users Start Menu>. Prompt Before Running: always enable this option.

26

2003,

J.Cody

Outlook
This function configures the cosmetic attributes for your Install Project. When you enable a cosmetic feature that specifies the default text as {<AppName> Installation}, change the default text specification to {<AppName> Install / Upgrade}. This will alert users that your install package will automatically install or upgrade your application.

Dialogs
This function allows you to select the dialogs that will be presented to users. The dialogs listed below are appropriate for the PB/DOS install tactics that we have previously described. Welcome License (optional) Readme (optional and not needed if you install a readme.txt file) System Requirements Installing Finished Uninstall You do not need to select any other dialogs for PB/DOS installs.

System Info
Do not disable any of the configuration attributes that you intend to use as system requirements for installing your application.

Options
If you are installing a README file, use this function to specify whether and how it should be presented to the user.

Uninstall
Use this function to enable creation of a Control Panel <Add/Remove Software> entry and provide support information for your application.

System Req
Use this function to specify the base levels of compatibility supported by your application. Specify <Windows 95 or higher> and <Windows NT 4> to designate compatibility with Windows 95, 98, ME, NT4, 2000, and XP. Your specifications here determine what versions of Windows will be accepted or rejected as system requirements for your application. Our instructions accept all versions of Windows.

Files to Install
Use this function to identify all application files that should be included in your install package. We previously described <How to Build an Install Library>. We used library folders named <MODFILES> and <ALLUSERS> to store and classify files by the conditions that determine whether files should be installed: <MODFILES> do not overwrite existing files (except PIF files, all files that may be modified). <ALLUSERS> always overwrite existing files (all PIF files and all read-only files).

27

2003,

J.Cody

For now, you can ignore the <Installation tree> controls in the upper half of this dialog. Follow these instructions for each of our two install library folders: 1. Select <Add folder>. 2. Select library folder (MODFILES or ALLUSERS). 3. Select <Ok> to accept <InstallDir> as target folder. 4. Select <No> to reject recursion option. 5. Using Ctrl+mouse (or keyboard shift-key method) to highlight all <Source Files> added from the most recently selected library folder (MODFILES or ALLUSERS). 6. Select <Advanced>. 7. Select appropriate <Overwrite Mode> option: <Do not overwrite> or <Always overwrite>. 8. Select <Ok>.

Whenever you want to verify install conditions for any file, select <Files to Install> then double-click on the file.

28

2003,

J.Cody

Shortcuts
Uninstall Shortcut You may or may not desire to enable <Create Shortcut for Uninstaller> at the bottom of this function dialog. You have already enabled or disabled creation
of a Control Panel <Add/Remove Software> entry. Thus, you can direct InstallWizard to create either or both of these ways for users to launch an uninstall.

Application Shortcuts Use this function to define all Shortcuts that should be created by the Installer. Your purpose is to provide users with launching Shortcuts for each entry point to your application. We previously described <How to Build an Install Library>. For your application, library folder <ALLUSERS> should contain a PIF file for each entry point to your application. Most applications have one startup program (i.e., entry point). When this is the case, <ALLUSERS> should contain one PIF file. Follow these instructions for each PIF file that should have a Shortcut installed in the Start Menu group: 1. Select <Add>. 2. Select Shortcut Target <Browse>. 3. Select <Application Files>. 4. From <Files in folder>, select the appropriate PIF file. 5. Select <Ok>. 6. Replace whatever appears in the <Shortcut Name> variable with <ShortcutDir><\anyname> where <\anyname> is your own descriptive name (e.g., <ShortcutDir>\KeepScore). You do not need to specify a file extension. Select Icon file <Browse>. Select <Application Files>. From <Files in folder>, select the appropriate ICO file. Select <Ok>. Select <Ok>.

7. 8. 9. 10. 11.

29

2003,

J.Cody

If you desire to install Desktop Shortcuts, you must <Add> a Shortcut for each family of Windows versions (95/98/ME and NT4/2000/XP). The only difference between these Desktop Shortcuts is <Shortcut Name> as shown below.

Windows 95/98/ME Desktop Shortcut

Windows NT4/2000/XP Desktop Shortcut

Desktop Shortcuts can be <Add>ed by essentially following the instructions for <Add>ing Start Menu Shortcuts. The only difference is Step 6, where <Shortcut Name> should reference either <Desktop> or <DesktopNt> instead of <ShorcutDir>. For <DesktopNt>, the option you selected in function General determines whether the Shortcut is added to the All Users Start Menu or the Current User Start Menu (i.e., the current user during actual installation). Note: if you adhere to our install tactics, you never specify a <Command Line> when you <Add> Shortcuts. However, you must ensure that <Working Dir> specifies <InstallDir>. The result will be that Installer created Shortcuts will inherit <Command Line> and other run-time properties from the PIF files that you created.

30

2003,

J.Cody

Advanced
This function contains two <Miscellaneous Settings> that require attention. For <Action to take when> select option <Always overwrite>. This option setting does NOT override the install conditions that you specified in function Files to Install. However, it will apply if you failed to specify an install condition for any of your application files. We recommend <Always overwrite> for the production version of your install package. During testing, you may select <Ask User> to help you detect errors of omission with respect to install conditions for your application files. Since you are installing a DOS application, version checking options for Windows EXE and DLL files are not applicable. To effectively use this feature, you would need to install a dummy Windows EXE or DLL. Disable (uncheck) <Check for previous installations>. Do not enable this option without an understanding of how the Installer depends upon System Registry settings to check for previous installs. By disabling this option, you will not have to be concerned with registry settings. Our install/upgrade tactics do not depend upon entries in the registry.

Create Setup
This function creates your installation package as a compressed self-extracting executable suitable for distribution via the Internet or on CD media. Other media output options are also available. Before you select the action command button in function <Create Setup>, you may change <Setup filename> to specify the executable filename for your install package.

How to Modify Dialogs

When you test your application install package, you may notice dialog attributes that you would like to change or customize: Start InstallWizard. Select <Files>. <Open> your install project. Select <Dialogs>. Double-click on a listed dialog to open the selected dialog in the Astrum Dialog Editor. Use your mouse to select text frames, command buttons, or other objects that you desire to change. An appropriate set of edit controls will appear for each object that you select. Remember to save your changes. From the main InstallWizard window, you can select <Help>, <Contents>, <Miscellaneous>, and <Dialog Editor> to learn more about the Astrum Dialog Editor.

31

2003,

J.Cody

Recommended PB/DOS Run-Time Properties

When you create Win 95/98 PIF files for your application, you must specify runtime properties for your executable files. As previously described, application launching Shortcuts created the Installer will inherit run-time properties from the PIF files that you create. In the following pages, we present illustrations of Windows XP Shortcuts created by the Installer. These examples: Show how run-time properties inherited from your PIF files will be presented to users if they choose to inspect <Properties> for launching Shortcuts. Show a recommended set of run-time properties that should be specified when you create PIF files for most PB/DOS applications. Where appropriate, we will describe Win 95/98 PIF properties that are not selfevident in the Win XP Shortcut illustrations.

32

2003,

J.Cody

Win XP Shortcut KeepScore Installed by InstallWizard

InstallWizard Shortcut Definition Note that target link is PIF file installed in application folder.

From Installer.

33

2003,

J.Cody

From topmost <Program> tab variable in W95PIF01. From W95PIF01. From Installer. From W95PIF01. From W95PIF01. From W95PIF01. From W95PIF01.
Advanced tab in W95PIF01 enabled <Suggest MS-DOS Mode>. This is not shown in Win XP shortcuts.

From Font Tab in W95PIF01.

W95PIF01 contained default settings for fonts.

34

2003,

J.Cody

All settings are from W95PIF01.

<None> is recommended for EMS.

<Auto> is not recommended if your application uses PB/DOS tools to access XMS. For such tools, you must avoid XMS memory options that could produce XMS allocations which exceed the arithmetic limits of the PB/DOS tool.

35

2003,

J.Cody

All settings are from W95PIF01.

Not Shown: <Display Toolbar> is enabled in Win95PIF01. This is desirable. When <Full-screen> and <Display Toolbar> are enabled, users may still run in VDM or NTVDM windows by enabling keys Alt+Enter and Alt+Esc in the Misc tab. <Display Toolbar> is enabled for the benefit of Win 95/98/ME users.

36

2003,

J.Cody

All settings are from W95PIF01. Users who want to run in VDM or NTVDM windows may enable keys Alt+Enter and Alt+Esc. Alt+Enter toggles mode back and forth between full-screen and runin-window. This technique is usually more desirable than locking users into either mode.

37

2003,

J.Cody

None of these settings exist in W95PIF01. None of these option settings are necessary for PB/DOS applications that have been modified for universal compatibility. Win XP may set Windows 95 mode by default on some user systems, but this is not a requirement.

## End ##

38