The Developer Connection - Device Driver Kit for OS/2 3

home *** CD-ROM | disk | FTP | other *** search

/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / devtools / apl2 / read.me < prev next >

Wrap

Text File | 1993-12-17 | 33.1 KB | 870 lines

======================================================================== IBM* APL2* for OS/2* read.me file: APL2 for OS/2 Version 1.0D - Demo (C) Copyright IBM Corp. 1994. All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. ======================================================================== ======================================================================== About this demo version ======================================================================== This demo version is equivalent to APL2 for OS/2 Advanced Version 1.0 except for a built in expiration date of 6/30/94. Please feel free to distribute this product freely, as long as no part of the product is modified in any way. ======================================================================== APL2 for OS/2 Installation ======================================================================== You should have 4 diskettes. To install: 1. Insert diskette 1 in your computer and type a:install (or b:install if you are installing from drive B). 2. When you see the Instructions window, click on 'Continue' (or press 'Enter'). 3. From the Install window, click on 'OK' (or press Enter). You should leave the box marked 'Update config.sys' checked so the install program can make the necessary modifications. 'Overwrite files' can be left unchecked. 4. In the Install - directories window, click on 'Select All'. 5. Click on 'Disk Space' for a list of possible target drives. Selecting a drive displays a message telling you if there is enough space for the install. If you select a new drive, check the box 'Change directories to selected drive'. 6. If desired, change the name of the install directory. 7. Click on 'Install' to begin installation. 8. You are prompted for the other disks during the install. When the last disk is finished, select 'Exit' from the 'File' menu of the Install window. 9. You need to reboot your machine before the changes to config.sys can take affect. ======================================================================== APL2/2 Font Installation ======================================================================== APL2/2 is shipped with several different PostScript** and bitmap fonts. Be sure to read the section on 'Installing the APL2 Fonts' in the APL2/2 User's Guide before attempting to start APL2/2. NOTE: the APL2NORM (facename APL2) font is not provided with the APL2/2 product. Please ignore any reference to this font in the User's Guide. ======================================================================== If you have previously installed a beta version of APL2 for OS/2: ======================================================================== APL2/2 version 1.0 should not be installed over an existing beta version of APL2/2. If you have a beta version installed you should do the following: 1. Delete the APL2 for OS/2 Spin x folder and all of its contents. Click mouse button 2 on the folder and select 'Delete'. 2. Delete the top-level install directory (default = C:\APL2OS2) and all of its subdirectories. Use OS/2 'Drives', click mouse button 2 on the top-level directory and select 'Delete'. 3. Uninstall any installed fonts from previous beta versions. See 'Uninstalling fonts'. ======================================================================== The APL2/2 Installation Utility ======================================================================== The APL2/2 Installation Utility can be invoked by clicking mouse button 1 on the Installation Utility icon in the APL2/2 folder. This utility can be used to Update, Delete, and Restore the APL2/2 product. When you invoke the utility after installing APL2/2, the Action menu can be used to Delete or Update the product. Update is used to install future updates or maintenance to the product. Delete can be used to remove the product from your hard disk. *** IMPORTANT *** In order to successfully use the Delete function, you must reboot your machine and invoke Delete before running APL2/2 or viewing the online documentation. Failure to do this causes Delete to fail and leaves the product in an unrecoverable state. After using the Installation Utility to delete the APL2/2 product, you must reboot your machine to finish the process. After deleting the product, do not use the Install action from the Installation Utility Action menu, use install from disk #1 of the APL2/2 product only. ======================================================================== Version 1.0 notes: ======================================================================== APL2/2 Folder After installation is complete, you will have a new folder on your OS/2 desktop called APL2 for OS/2 Advanced. Open the folder and click on the 'APL2/2 Users Guide' icon for information relating to this version. The folder also contains a program object that can be used to start APL2/2. This object should be considered a template to be customized by the user. In particular, you probably want to modify the following items in Settings: On the Program page, you should change 'Working Directory' to a directory where you would like your default workspace library and session manager log. On the Window page, you might want to change 'Open Object Behavior' to 'Create new window'. This allows you to start multiple APL2/2 sessions from the same object. Using OS/2 2.0 OS/2 2.0 Service Pak 1 or later or OS/2 J 2.1 or later are required to use APL2 for OS/2. Cooperative Processing In order to use the cooperative processing features of APL2/2, TCP/IP (Version 2.0 or later) must be installed and configured on your machine. The ifconfig program must be run before starting APL2/2. The APL2/2 Users Guide suggests using a processor profile entry with an :svopid. tag of 0. This is not currently supported. Printing AP 207 windows Printing of AP 207 windows that contain Bitmap or Images can cause the window to not print correctly. This is caused by the spooler inadvertently modifying the file. To correct this you can: 1. Disable the print spooler. or 2. Open your printer SETTINGS and select Queue Options. Check the printer specific format box and close the SETTINGS. (The picture viewer does not work on these printer specific items.) Using the APL2INFO.FON font - The APL2 Info font is designed for use with the APL2/2 online documentation only. It does not support the APL character set if selected for use with the Session Manager. APL2 SVP Trace Window Print Object Creation Failures When the APL2 SVP Trace window is opened, it attempts to create an APL2 Print Object. If no print queues exist on the system, creation of the APL Print Object fails. When this condition is encountered, the SVP Trace window displays a message box. This message box is informational; it does not indicate an error. The Printer Setup and Print options on the File menu are not available. Printing APL Characters Using Hewlett-Packard LaserJet** Print Drivers The LaserJet drivers supplied with the GA levels of OS/2 2.0 and OS/2 2.1 have a bug when the APL font is downloaded. When attempting to print APL characters, although the driver causes the printer to print the file, the downloaded APL characters are not printed. To print APL characters, open the Printer driver page of the LaserJet settings, then open the printer driver settings and select Device Defaults. In the Device Defaults window, check the Fast System Fonts option. This option turns off the Print Driver's code to download the APL font. Printing APL Characters Using PostScript Print Drivers The PostScript driver supplied with the GA levels of OS/2 2.0 and OS/2 2.1 has a problem involving downloaded fonts. When attempting to print APL characters, although the driver produces a PostScript file, the file is unusable. When sent to a printer, the file is discarded by the printer. To print APL characters, check the Printer Specific option on the Queue Options page of the settings notebook of the printer object. This option turns off the print driver's code to build a PostScript file that downloads the APL font. Since the font is not downloaded, each APL character is drawn as a series of lines. PostScript files containing APL characters can be very large and the time required to generate the file can be very long. To avoid these problems, select a non-PostScript driver, if possible. Using the APL2/2 Session Manager to Control APL2/370 Sessions AP 120 can be used to control a remote APL2/370 session if TCP/IP is installed on both OS/2 and the mainframe. APL2/370 does not use as many different codes as the workstation interpreters to distinguish different types of output. Several types of output mentioned in the session manager's Fields window are identified differently by APL2/370. Keyboard Layout Modification Window Font Error The APL2 Keyboard Handler is used to enable entry of APL characters into PM windows. The APL2 Keyboard handler supports a Keyboard Layout Modification window. The Keyboard Layout Modification window is supposed to display the keyboard layout using the same font that the APL-enabled window is using. The modification window determines the APL-enabled window's font by querying the metrics of the window's default font. This works if the window uses the font Local Identifier (LCID) 0. It does not work for windows that use an LCID other than 0. Multiple Line Entry (MLE) fields do not use LCID 0. The Keyboard Modify choice (on the Options menu of the window opened by the EDIT function in the PMTOOLS workspace) uses an MLE and the APL2 Keyboard Handler. When the Keyboard Modify choice is selected from the EDIT window Options menu, the Keyboard Layout Modification window does not display the layout using the correct font. Applications that need to use the APL2 Keyboard Handler to enable entry of APL characters into an MLE can use a second invisible window to invoke the Keyboard Layout Modification window. Subclass a second window, that is not an MLE and that can be invisible, using the Keyboard Handler and send the APLKEY_MSG_MODIFY message to the second window. Uninstalling Fonts When you boot OS/2, the system opens all the installed bitmap font files and leaves them open until you shut down the system. When you use either a bitmap or PostScript font, OS/2 opens the font file, if it is not already open, loads the font into storage and does not delete it from storage until you shut down the system. Furthermore, if you shut down the system while an application is using a font, OS/2 can restart the application when you restart the system. This causes the font to be opened and loaded again. Because OS/2 usually has both the font loaded and the font file open, you can not just uninstall the font; it is in use. To uninstall the font, you must ensure that the font is not loaded and that the font file is not open. The following steps describe this process.. First use the Font Palette's Delete Font dialog to remove the font from OS/2's list of installed fonts. If the font has already been loaded, the Delete Font dialog may tell you that the font is in use by another program. If this happens, first make sure that no application is using the font, then Reboot and try this step again. If the font was not loaded (as should be the case just after a reboot), the Delete Font dialog will delete the font from the list of installed fonts. However, it may then tell you that the font file is in use. This is because OS/2 leaves open all font files it opens until you reboot. However, since the Delete Font dialog has now removed the font from the list of installed fonts, the file is not opened the next time you reboot. So, reboot again. Now the font is neither loaded nor open. However, the font file still exists in the directory that OS/2 uses to store fonts. You cannot use the Font Palette to delete this file since the palette only shows OS/2's list of installed fonts. To finish the font uninstallation process, you must delete the file manually using the OS/2 Delete command. Open an OS/2 window or full-screen session, change into the directory into which the Add Font dialog copied the font, and delete the font file. Notes: Even if you received no error messages when you first attempted to uninstall a PostScript file that has been used since the last boot, you need to reboot before you can reinstall the font. This is because OS/2 still has a copy of the font in storage even though it is uninstalled. On an OS/2 2.0 system, the default font directory is called: C:\OS2\DLL\ On an OS/2 2.1 system, the default font directory is called: C:\PSFONTS\ Finally, you may wonder why OS/2 always leaves the font files open and the fonts loaded. There is a good reason for this: performance. The OS/2 developers traded convenience during the font uninstallation procedure for increased performance during normal operation. ======================================================================== An Overview of DBCS Support Provided by PM ======================================================================== The Presentation Interface supports double-byte character sets (DBCS) by means of three kinds of character-encoding schemes: SBCS only Single-byte code pages; for example, U.S.-English. Both ASCII and EBCDIC SBCS code pages have similar representations. DBCS only Double-byte code pages; for example, Kanji. Both ASCII and EBCDIC DBCS code pages have similar representations. MIXED Code pages that incorporate a combination of single-byte and double-byte characters. The internal representations of EBCDIC MIXED and ASCII MIXED code pages differ: o ASCII MIXED: the encoding scheme allows single-byte characters to be distinguished from double-byte characters algorithmically. With this scheme the number of characters entered or displayed is the same as the number of characters in a field. o EBCDIC MIXED: the encoding scheme requires that control characters within the string switch from single- to double-byte encoding (and from double- to single-byte encoding). These control characters are the shift-out (SO) and shift-in (SI) characters. With this encoding scheme there may be many more characters in the input or data field than characters displayed or printed. All MIXED strings are displayed without a space between sequences of single-byte and double-byte characters (unless spaces are explicitly included in these positions within the string). For graphics, selection of a local identifier (lcid) identifies the code page in force, and therefore whether subsequent character strings are to be interpreted as SBCS, DBCS, ASCII MIXED, or EBCDIC MIXED. DBCS Support Provided by APL2 for OS/2 APL2/2 supports use of DBCS characters in application programs including Presentation Manager* windows. OS/2, and hence APL2/2, do not support use of both APL2 and DBCS characters in any single PM window except when using the OS/2 Graphical Programming Interface (GPI) services. APL2 Print object windows require that a SBCS codepage be available. At least one SBCS codepage must be listed in the CODEPAGE statement in config.sys. If no SBCS codepage is listed in the CODEPAGE statement, attempts to create APL2 Print Object windows fail. Note: There are currently two bugs in OS/2 J that affect the use of APL characters: 1) When a PostScript font is first loaded after booting the machine, PM associates the current codepage with the font. The font continues to be associated with that codepage until the machine is rebooted even if the font is unloaded or the process codepage is changed. If the current codepage is any codepage other than 850, then APL characters do not display correctly in several PM controls and APL characters can not be entered in Entry Field Controls. Use the following procedure to effectively use the APL PostScript fonts included in APL2/2: List codepage 850 in the CODEPAGE statement in config.sys. After booting and before running any program that uses the APL font, switch to codepage 850 using the CHCP command. From the process that is using codepage 850, run any program that loads the APL font. 2) APL characters can not be written to Entry Field controls that have the ES_SBCS attribute flag using WinSetWindowText. OS/2's DBCS recognition scheme is activated during WinSetWindowText; the APL characters are interpreted as DBCS characters; the Entry Field control beeps, and the control text is not changed. This problem does not effect any part of the APL2/2 Programming Environment. Applications that allow entry of APL characters in entry fields should not use ES_SBCS. APL2/2 Support for DBCS Characters in Application Windows: Characters to be displayed in PM windows or passed to other OS/2 applications are stored in the APL2/2 workspace as single-byte characters. It is the responsibility of the application or PM window to use the encoding scheme specified by the current codepage to detect the existence of DBCS characters in any APL2 character vector. When a DBCS or MIXED codepage is in effect, the following behavior results: When a character vector is passed to a PM window, any DBCS data encoded in the vector is displayed as DBCS characters. When the character content of a PM window is retrieved, the contents are returned as a vector of single byte-characters. It is the responsibility of the application to use the encoding scheme specified by the current codepage to detect the existence of DBCS characters in the vector. Note: In many cases, the application need not perform any special processing of DBCS data. It can be passed intact back to PM for display. It can also be written as binary data to a file and retrieved from a file intact. Three auxiliary processors supplied with APL2/2 can be used to control PM windows: AP 124 AP 124 is APL2's Text Display processor. AP 124 allows applications to format a window by defining input and output fields, control the colors and other attributes of defined fields, write text to and read text from defined fields, and process keyboard input. AP 124 supports display and entry of DBCS characters. AP 124 windows include a DBCS Keyboard Shift Status Area. AP 124 supports entry of DBCS characters into input fields. AP 124 also provides support for applications to detect individual keystrokes. This support only operates correctly when the keyboard is in SBCS entry mode. When the keyboard is in DBCS mode results are unpredictable. Note: AP 124's default operation causes an APL2 font to be selected when a window is opened. Since APL2 fonts do not include DBCS characters, they are inappropriate for display and entry of DBCS characters. If AP 124's APL input mode is turned off before opening a window, AP 124 selects a non-APL font. If the current process codepage is a SBCS codepage, the System Monospaced font is selected. If the current process codepage is a DBCS codepage, the Mincho font is selected. AP 145 AP 145 is the APL2-PM interface processor. AP 145 provides access to the PM window (Win) and graphical programming interface (Gpi) services. These services can be used to create and process PM windows that provide full DBCS support. AP 145 does not provide DBCS support; rather, AP 145 provides access to PM, which provides the necessary support for building DBCS enabled OS/2 applications. The DBCS supported provided by PM is described in the documentation supplied with the OS/2 Developer's Toolkit. The "DBCS Design Guide and Information for OS/2 Programming" manual, GA18-7284, also includes useful information for developers of DBCS enabled applications. In brief, DBCS input is enabled for those PM frame windows that include the frame control flag FCF_DBE_APPSTAT. The Entry Field Control Styles ES_SBCS, ES_DBCS, ES_MIXED, and ES_ANY can be used to control the type of data allowed in entry fields and comboboxes. The AP 145 documentation describes how to use the Dialog Editor component of the OS/2 Developer's Toolkit to build simple SBCS dialogs. The Dialog Editor provides support for setting the appropriate frame and controls styles for enabling DBCS support in dialogs. The Dialog Editor's online help should be consulted for information about setting these styles. AP 207 AP 207 is APL2'2 Graphics Processor. AP 207 provides high-level support for drawing graphics primitives (such as arcs, lines, polygons, and characters) in PM windows. AP 207 supports display of DBCS characters. If the current codepage is a DBCS or MIXED codepage, and if a font containing DBCS characters is selected, DBCS characters can be displayed in an AP 207 window. When a character vector is passed to an AP 207 window, any DBCS data encoded in the vector is displayed as DBCS characters. AP 207 does not support entry of character vectors; rather, AP 207 provides support for applications to detect individual keystrokes. This support returns the same character codes and keyboard scancode provided by AP 124. AP 207 windows do not include a DBCS Keyboard Shift Status Area. Entry of DBCS characters is not supported. APL2/2 Support for DBCS Characters in File Names AP 210, AP 211, and the FILE external function all support DBCS characters in file names. Like the window interface processors, AP 210, AP 211 and FILE use vectors of single-byte characters for file names. The file name is passed directly to the OS/2 Control Program file services. The encoding scheme specified by the current codepage is used to interpret the bytes in the file name. This support allows applications to pass file names entered in PM windows directly to the file processors. APL2/2 Support for Printing SBCS and DBCS Characters This section describes how OS/2 distinguishes between SBCS and DBCS characters and the DBCS requirements of print objects. This background information is required in order to understand how to print APL characters when using OS/2 J. OS/2 processes character strings one or two bytes at a time. SBCS characters are represented by one byte; DBCS characters are represented by two bytes. The current codepage identifies byte values that represent SBCS characters. The current codepage also identifies byte values that are the first bytes of pairs of bytes that represent DBCS characters. As a character string is processed, if a byte corresponds to a SBCS codepoint in the current codepage, then the byte is used to display or print the corresponding SBCS character. If a byte corresponds to a codepoint that indicates that the byte is the first of a pair of bytes representing a DBCS character, then the pair of bytes is used to display or print the corresponding DBCS character. This algorithm conflicts with APL characters since APL characters are located at codepoints that DBCS codepages identify as first bytes of DBCS byte pairs. This conflict is irrelevant on machines that only support single-byte characters. However, on machines that support double-byte characters, it interferes with printing APL characters. By default, APL2 Print Objects enable the current codepage's encoding scheme for distinguishing between SBCS and DBCS characters in character strings. DBCS characters encoded in a string are printed as DBCS characters. Therefore, APL characters cannot be printed on DBCS machines using a print object in its default mode. Print object windows require that a SBCS codepage be available. At least one SBCS codepage must be listed in the CODEPAGE statement in config.sys. In order to print APL characters on DBCS machines, use the APLPRT_SET_SBCS message to cause the print object to select the SBCS codepage and disable OS/2's DBCS recognition algorithm. APLPRT_SET_SBCS Parameters The first parameter is a Boolean short. If it is 1, the DBCS algorithm is disabled; all data is printed as single-byte characters. If it is 0, the DBCS algorithm is enabled; DBCS characters can be printed. Note: Print objects' word break algorithm does not support DBCS characters. Migration of APL2 Programs Containing DBCS Characters from APL2/370 OS/2 distinguishes between DBCS and SBCS characters algorithmically. The algorithm used depends on the current codepage. In order to correctly support display and entry of DBCS characters, APL2/2 applications should use OS/2's algorithmic approach for managing DBCS characters. APL2/370 uses a 4-byte format for storing DBCS data. The first two bytes contain the codepage identifier (CPGID), the value specified in the APL2/370 DBCS invocation option, or zero. If the first two bytes are not zero, the second two bytes contain the codepoint in the codepage. If the first two bytes are zero, the third byte is also zero and the fourth byte is an EBCDIC character. The APL2/2 interpreter supports APL2/370 format 4-byte characters. Programs containing 4-byte characters can be migrated from APL2/370 to APL2/2. However, APL2/2 does not provide support for translation of 4-byte characters to any of the OS/2 character-encoding schemes. The following procedure can be used to extract the codepage identifier and codepoint from a 4-byte character: Use the QuadAF system function to convert the 4-byte character to an integer. Use the Encode primitive to convert the integer into two base 256 integers. The first integer is the codepage; the second integer is the codepoint. Note: CMS and TSO support a different set of codepages than OS/2 supports. DBCS Support in the APL2/2 Programming Environment The APL2/2 programming environment includes three major components: Session manager Object editor, accessed from the session manager APL file editor, Apledit These components support entry of APL characters in the session log, APL object definitions, and text files. The components do not support display or entry of DBCS characters in the log, definitions, or files. They also do not support display or entry of DBCS characters in their Find, Open Object, or Function Key windows. Within the APL2/2 programming environment, OS/2 generated facilities such as system menus and push buttons display DBCS characters. The session manager and file editor both support use of DBCS characters in file names. The session manager and editors display only SBCS characters. Characters that DBCS-enabled windows would display as DBCS characters are displayed as SBCS characters. These examples all display as SBCS characters: DBCS characters received from PM through AP 145 DBCS characters in literals in defined programs DBCS characters in comments in defined programs The session manager displays 4-byte DBCS characters as omega characters. The object editor can not be used to edit arrays containing 4-byte characters. ======================================================================== File structure ======================================================================== apl2os2 | |---read.me |---apl2os2.pkg |---aplisinc.pkg |---apliprcs.exe |---aplipii.dll |---aplinsts.exe |---apliexts.dll |---aplimsg.msg |---apliicis.ico |---aplihplb.hlp | |---bin | | | |---aosapl2.exe | |---ap100.exe | |---ap119.exe | |---ap120.exe | |---ap124.exe | |---ap127.exe | |---ap145.exe | |---ap207.exe | |---ap210.exe | |---ap211.exe | |---apl2.cmd | |---apl2.ico | |---apl2logo.exe | |---apl2psrv.exe | |---apl2road.ico | |---apl2svp.prf | |---apl2svp.prm | |---apl2svpt.exe | |---apl2tcps.exe | |---apl2util.exe | |---apl2db2.cmd | |---apldb2cs.bnd | |---apldb2rr.bnd | |---apldb2ur.bnd | |---apledit.exe | |---aplnm011.nam | |---demo145.res | |---en_uk.nlt | |---en_us.nlt | |---fr_fr.nlt | |---gr_gr.nlt | +---it_it.nlt | |---dll | | | |---apl2crt.dll | |---apl2svp.dll | |---apl2svpn.dll | |---apl2svpt.dll | |---apl2xtrn.dll | |---aplna011.dll | |---aplpm.dll | |---demo145.dll | |---fonts | | | |---ap124fnt.fon | |---apl2info.fon | |---apl2ital.afm | |---apl2ital.pfb | |---courapl.afm | |---courapl.pfb | |---couraplb.afm | |---couraplb.pfb | |---goteng.avf | |---gotger.avf | |---gotita.avf | |---greser.avf | |---gresim.avf | |---markers.avf | |---modsim.avf | |---romdup.avf | |---romdupf.avf | |---romita.avf | |---romitab.avf | |---romser.avf | |---romserb.avf | |---romsim.avf | |---romsimm.avf | |---sanser.avf | |---sanserf.avf | |---script.avf | |---thkrndf.avf | |---thkrndo.avf | |---thksquf.avf | +---thksquo.avf | |---help | | | |---ap120.hlp | |---ap120edt.hlp | |---ap145.hlp | |---ap207x.hlp | |---apl2osug.inf | |---applsvpt.hlp | |---apledit.hlp | |---aplkey.hlp | |---aplpm.inf | +---aplprint.hlp | |---include | | | |---aplap.h | |---aplobj.h | |---aplpm.h | |---aplsvi.h | +---apserver.h | |---lib | | | |---apl2dll.obj | |---aplpm.lib | +---apl2svp.lib | |---samples | | | |---ap999.c | +---apsample.atf | |---wslib1 | | | |---display.apl | |---edit.apl | |---examples.apl | |---idioms.aof | |---idioms.apl | |---mathfns.apl | |---time.apl | +---utility.apl | +---wslib2 | |---ap124.apl |---demo124.apl |---demo145.apl |---demo207.apl |---file.apl |---graphpak.apl |---migrate.apl |---os2.apl |---pmtools.apl |---pmwin.apl |---printws.apl +---sql.apl ======================================================================== Support ======================================================================== We'd like to hear from you! Please report any comments, suggestions, or problems through one of the following channels: Internet: apl2@vnet.ibm.com FAX: (408) 463-4488 Mail: APL Products & Services IBM Santa Teresa Laboratory, M46/D12 555 Bailey Ave. San Jose, CA 95141 CompuServe: go IBMAPL2 ======================================================================== Trademarks ======================================================================== The following terms are trademarks of the IBM Corporation. They are denoted by an asterisk (*) when they first appear in the text. APL2 IBM OS/2 Presentation Manager The following terms are trademarks of other companies. They are denoted by a double asterisk (**) when they first appear in the text. PostScript Adobe Systems, Inc. LaserJet Hewlett-Packard, Inc.