═══ 1. How to Use the 'PL/I for OS/2 Toolkit Reference' ═══ The PL/I for OS/2 Toolkit Reference provides information about how to use the following tools provided in IBM PL/I for OS/2 Toolkit: o Visual PL/I creates Presentation Manager (PM) applications for the PL/I for OS/2 development environment. Visual PL/I allows you to create graphical user interface (GUI) applications visually, and then generates the underlying PL/I code and PM calls. o C2PLI conversion aid helps you convert C header files to PL/I include files. Before you begin to use this information, it would help you to understand how you can: o Expand the Contents to see all available topics o Obtain additional information for a highlighted word or phrase o Use action bar choices How to Use the Contents When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available for you to select. To expand the Contents if you are using a mouse, click on the plus sign that is next to the selection. If you are using the keyboard, use the Up Arrow () or Down Arrow () key to highlight the topic, and press the plus (+) key. For example, Type functions has a plus sign beside it. To see additional topics for that heading, click on the plus sign or highlight that topic and press the plus (+) key. To view a topic, double-click on the topic, or press the Up or Down Arrow key to highlight the topic, and then press the Enter key. How to Obtain Additional Information After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words and phrases are highlighted in green letters, or in white letters on a black background. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window. How to Use Action Bar Choices Several choices are available for managing information presented in PL/I for OS/2 Toolkit Reference. There are three pull-down menus on the action bar: the Services menu, the Options menu, and the Help menu. The actions that are selectable from the Services menu operate only on the active window that is currently displayed on the screen. These actions include the following: Bookmark Allows you to set a placeholder so you can retrieve information of interest to you at a later time. When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all of the bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, choose the Bookmark option from the Services pull-down. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Click on the Place radio button, or press the Up or Down Arrow key to select it. 5. Click on OK (or select it and press Enter). The bookmark is then added to the bookmark list. Search Allows you to find occurrences of a word or phrase in the current topic, selected topics, or all topics. You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list. To search for a word or phrase in all topics, do the following: 1. Choose the Search option from the Services pull-down. 2. Type the word or words to be searched for. 3. Click on All sections, or press the Up or Down Arrow key to select it. 4. Click on Search (or select it and press Enter) to begin the search. 5. The list of topics where the word or phrase appears is displayed. Print Allows you to print one or more topics. You can also print a set of topics by first marking the topics in the Contents list. To print the Contents list of the document, do the following: 1. Choose Print from the Services pull-down. 2. Click on Contents, or press the Up or Down Arrow key to select it. 3. Click on Print (or select it and press Enter). 4. The Contents list is printed on your printer. Copy Allows you to copy a topic that you are viewing to the System Clipboard or to a file that you can edit. This is particularly useful for copying syntax definitions and program samples into the application that you are developing. You can copy a topic that you are viewing in two ways: o If you select Copy, the topic that you are viewing is copied into the System Clipboard. If you are using a Presentation Manager* (PM) editor (for example, the Enhanced Editor) that copies or cuts (or both) to the System Clipboard, and pastes to the System Clipboard, you can easily add the copied information to your program source module. o If you select Copy to file, the topic that you are viewing is copied into a temporary file named TEXT.TMP. You can later edit that file by using any editor. TEXT.TMP is placed in the directory where your viewable document resides. To copy the contents of a topic, do the following: 1. Expand the Contents list and select a topic. 2. When the topic appears, choose Copy to file from the Services pull-down. 3. The system puts the text pertaining to that topic into the temporary file TEXT.TMP. For information on any of the choices in the Services pull-down, highlight the choice and press the F1 key. The actions that are selectable from the Options menu allow you to change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose Expand all from the Options pull-down. You can also press the Ctrl and * keys together. For information on any of the choices in the Options pull-down, highlight the choice and press the F1 key. The actions that are selectable from the Help menu allow you to select different types of help information. You can also press the F1 key for help information about the Information Presentation Facility (IPF). ═══ Related Information ═══ o Copyright o Edition Notice o Notices o Trademarks and Service Marks ═══ 1.1. Copyright ═══ Copyright International Business Machines Corporation, 1994. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM* Corp. ═══ 1.2. Edition Notice ═══ First Edition, July 1994. This edition applies to Version 1 Release 1 of PL/I for OS/2 Toolkit, Part Number 1322966, and to all subsequent releases and modifications until otherwise indicated in new editions. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; any such changes will be reported in subsequent revisions. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any ways it believes appropriate without incurring any obligation to you. ═══ 1.3. Notices ═══ Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Armonk, NY 10504. ═══ 1.4. Trademarks and Service Marks ═══ The following terms, denoted by an asterisk (*) in this publication, are trademarks or service marks of IBM Corporation in the United States or other countries: Common User Access CUA IBM OS/2 Presentation Manager PS/2 ═══ 2. About This Book ═══ This book explains how to use the following tools provided in IBM* PL/I for OS/2* Toolkit: Visual PL/I for OS/2 creates Presentation Manager* (PM) applications for the PL/I for OS/2 development environment. Presentation Manager is the graphical user interface (GUI) for the IBM OS/2 operating system. C2PLI conversion aid helps you convert C header files to PL/I include files. ═══ 2.1. How This Book is Organized ═══ To design graphical user interfaces, or to develop the online help for it, see Getting Started with PL/I for OS/2 Toolkit and Designing Your User Interface. To write, link, compile, and run the final application, see Creating a Working Application. To help you create GUIs, see Tutorials. The first tutorial provides all the instructions you need. Advanced users of Visual PL/I and Presentation Manager may want to go directly to the tutorials in the back of the book in order to quickly explore Visual PL/I. To help you convert C header files to PL/I include files using the C2PLI conversion aid, see C2PLI Conversion Aid. For advanced users, such as creating your own code blocks, see the Appendixes. They also provide reference material related to Visual PL/I functions and error messages. Throughoutthisbook ,helpfultipsonusingVisualPL / Iarehighlightedforyou . ═══ 2.2. Before Using Visual PL/I ═══ o If you are designing a GUI, you need to know how to use OS/2: - Select and deselect items in a window - Use scroll bars - Use push buttons, radio buttons, and check boxes - Identify which window is the active window - Make a window active - Move windows - Change the size of windows - Maximize, minimize, and restore windows - Use the menu bar and select options from the related menus - Use the OS/2 system menu For more information, read the OS/2 online tutorial entitled "Introducing OS/2". The topics "Introduction" and "Windows" provide helpful information about windows. Also, refer to information on using OS/2 panel interfaces in the OS/2 Application Design Guide. o If you are developing online help for an application, you need to know how to use OS/2, and how to mark (tag) the text for the Information Presentation Facility (IPF) format used by OS/2. The Information Presentation Facility Guide and Reference contains details on using IPF. See Related Publications. o If you are developing an application, you need to be familiar with the PL/I language. ═══ 2.3. Related Publications ═══ You may find the following publications helpful when using PL/I for OS/2 Toolkit. Order numbers are listed in Bibliography. o IBM OS/2 Application Design Guide This book provides information on using OS/2 panel interfaces. o Presentation Manager Programming Reference, Volume 1 to Volume 3 These books provide reference type information on OS/2 Presentation Manager. After you install the OS/2 Developer's Toolkit, you can view these books online by selecting them in the Toolkit Information folder. o Information Presentation Facility Guide and Reference This book describes OS/2's Information Presentation Facility (IPF), the mechanism that handles help text. After you install the OS/2 Developer's Toolkit, you can view this book online by selecting it in the Toolkit Information folder. o Object-Oriented Design: IBM Common User Access Guidelines, SC34-4399 This book describes the guidelines that define the Common User Access* (CUA*) user interface. These guidelines can help you develop consistent look and feel for your OS/2 Presentation Manager applications. ═══ 2.3.1. Softcopy Publications ═══ The program that IBM licenses to you may include licensed publications in displayable or source form. Except as provided in this section, the terms and conditions of your license agreement with IBM apply to these publications and to any copies that you make from them. You may use the licensed publications in displayable or source form on all machines designated for this program. You may also copy and use the licensed publications on other machines in support of your authorized use of this program. To support your authorized use of the Program, you may make printed copies of the displayable or source material if you reproduce the copyright notice and any other legend of ownership on each copy or partial copy. ═══ 2.4. Program Service ═══ You can use CompuServe to submit problems to IBM and communicate directly with the PL/I product development team. For CompuServe membership information, call 1-800-848-8199 and request Representative 239. As a CompuServe member, you can access CompuServe using a modem. At the ! command prompt, type GO OS2DF1. Place your messages and comments regarding PL/I in "Section 6, REXX and Other Languages". If you are not a CompuServe user, send your comments to: IBM Corporation Department J41/D146 P.O. Box 49023 555 Bailey Avenue San Jose, CA 95161-9023 You can also fax comments to the attention of the PL/I development team at (408) 463-4820. ═══ 3. Getting Started with PL/I for OS/2 Toolkit ═══ This part introduces you to PL/I for OS/2 Toolkit. It shows you how to install PL/I for OS/2 Toolkit and takes you through the steps involved in getting started. It also provides an overview of the following functions that comprise PL/I for OS/2 Toolkit: o Visual PL/I o C2PLI conversion aid o OS/2 Developer's Toolkit ═══ 4. About PL/I for OS/2 Toolkit ═══ PL/I for OS/2 Toolkit contains the following tools: o Visual PL/I for OS/2 o C2PLI, a C-to-PL/I conversion aid o OS/2 Developer's Toolkit ═══ 4.1. Visual PL/I Simplifies Creating GUI Applications ═══ Visual PL/I is a powerful development environment for OS/2 PM applications. You can use it both as a design tool and as a code generator to develop programs quickly. Visual PL/I allows you to create GUI applications visually, or through a point-and-click method, and then it generates the underlying PL/I code and PM calls. With Visual PL/I, you can enjoy the following benefits. Design your user interface by selecting objects: Visual PL/I simplifies the process of creating graphics-based OS/2 applications by letting you paint an application onto the screen to create a prototype of the product you need, while it generates the background PL/I code and PM calls required to control the interaction between application components. PM programmers may also find many advantages to working with Visual PL/I. By automating the procedure of programming for windows, Visual PL/I allows developers to concentrate on program design and function, rather than on the complexities of the coding process. With Visual PL/I, it is no longer necessary to be a programmer in order to create a GUI. You can experiment with the `look and feel' of the product until it looks exactly the way you want it to. You can work on several projects at once, so you can copy windows and controls between applications. And, at any time while building an application, you can switch to test mode. Generate PL/I code automatically: Visual PL/I writes code automatically for the application you design. You can compile and link this code to create a working prototype of your application. You can also use Visual PL/I code blocks to create a working application. Visual PL/I generates the following files: Source file Contains the source code for the program, written in PL/I programming language. Header file Supplies function declarations and definitions of identifiers used in the program. Resource file Defines the resources (windows, menus, dialog boxes, and icons) used by the application. It may reference other files, for example, a dialog resource file (.dlg) containing dialog box specifications. Make file Contains instructions for compiling and linking an application. You can also import your own files for incorporation into an application. Build a library of commonly used code blocks: Visual PL/I has a code block facility that allows you to build and maintain a library of reusable code blocks. You can create reusable code blocks as required, and then add the tested code blocks into the library for use within different applications. Create online help: You can write online help, which is linked automatically and presented using IPF. You can create two levels of help: o Help for windows (extended help) o Help for individual controls (contextual help) Get customers involved in design decisions early: Because you can prototype quickly, you can invite customers to participate with you in designing the product. Once you select the output files required, you can generate the related code at any time, from a Visual PL/I menu. Use accelerator (shortcut) keys: Accelerators are combinations of keystrokes that, when selected, are interpreted as commands to the application. Accelerator keys are also known as shortcut keys. When you assign accelerators, Visual PL/I automatically creates the accelerator tables that are defined to OS/2 in order for the accelerator keys to actually work in your application. Use all OS/2 colors and fonts: In OS/2, you have access to the following types of palettes: o Scheme palette o Color palette o Font palette As you use Visual PL/I to create an application, you can use all three of these palettes to create a variety of colors and fonts for your windows. Using the drag and drop method, you can select the palette you want to use, and drop it into your application. To access any of these OS/2 color options, complete these steps: 1. Open the OS/2 System folder. 2. Select System Setup from the folder. 3. Select the type of palette you want to work with. 4. Select the color or font you want to add to your Visual PL/I design. Hold down mouse button 2 and drag the color or font selection directly into the Visual PL/I object. In addition to using a palette to create a color and font for an individual window, you can select a color scheme from the Color Scheme palette, drag it onto your project window, and create a color scheme that will flow through all windows you create for the project. ═══ 4.2. C2PLI Converts C Header Files to PL/I ═══ The C2PLI conversion aid helps you convert C header files into the equivalent PL/I include files. The tool minimizes manual conversion effort and allows you to easily incorporate C programs into your PL/I programming environment. ═══ 4.3. OS/2 Developer's Toolkit Provides Other Tools ═══ OS/2 Developer's Toolkit is a collection of application development tools for the PM programmer. Visual PL/I uses the following tools: o Header files o IPF compiler o Resource compiler o Make facility o Import librarian o Linker The Developer's Toolkit also includes the following useful online documents located in the Toolkit Information folder: o IPF Guide and Reference o Presentation Manager Programming Reference ═══ 5. Installing the Toolkits ═══ This section lists all system requirements for PL/I for OS/2 Toolkit, and provides instructions on how to install and run it on your workstation. It also contains all the basic information you need to start using Visual PL/I and the C2PLI conversion aid. Detailed instructions for completing specific tasks are included in the following chapters of this book. ═══ 5.1. What You Should Have ═══ The PL/I for OS/2 Toolkit product comes with this book and 12 diskettes. Before you install the diskettes, read the following sections. ═══ 5.2. System Requirements ═══ You can run PL/I for OS/2 Toolkit on any IBM PS/2* (or true compatible) You can run PL/I for OS/2 Toolkit on any IBM PS/2* (or true compatible) with at least an 80386SX processor. You need a fixed drive with at least 10MB for minimum configuration. Your workstation must have the following: o OS/2 Version 2.1 or later o PL/I for OS/2 Professional Edition Version 1.1 (10H7848), or PL/I for OS/2 Personal Edition Version 1.1 (10H7819) If youareworkingwithlargeprojects ,ensurethatyouhaveenoughfreespaceforthemontheswapperdrive .Forexample ,aprojectwith100windowscouldrequirebetween4and5Mofdiskspace . ═══ 5.3. Installing on Your Workstation ═══ The section guides you through the installation of: o IBM OS/2 Developer's Toolkit o IBM PL/I for OS/2 Toolkit You can install them from product diskettes onto your workstation's hard drive. The installation programs create the necessary subdirectories for you and will automatically update your CONFIG.SYS file, unless you choose to update your CONFIG.SYS file manually. For instructions on updating your CONFIG.SYS file manually, see Modifying Your CONFIG.SYS File. Online help is available throughout the installation program for each of the program's options, fields, and push buttons. You can get help either by selecting HELP, or by making the specific field or push button active and then pressing F1. ═══ 5.3.1. Installing OS/2 2.1 Developer's Toolkit ═══ The following installation directions assume that you are starting the installation procedure from diskettes in drive A. If you are starting your installation from another drive, substitute the letter of that drive (D or E, etc.) in the following steps for drive A. 1. Insert Diskette 1 into drive A. 2. From an OS/2 window or full-screen, change the current drive to drive A by issuing the following command: a: at the OS/2 command prompt. 3. Type install at the OS/2 command prompt and press Enter. The logo window appears. 4. Select OK. The Toolkit Information window appears. 5. Select the box for each component to be installed. 6. Select the Options pull-down. 7. To install one or more components on the default drive: a. Select Install. Follow the prompts in the message boxes to complete the installation on the default drive. 8. To install components on other drives: a. From the Options pull-down, select Set drives. The Toolkit Drive Selection window shows the selected Toolkit component and the current drive assignment. If you did not select a component for installation on the previous window, it does not appear in the window. To install a component on another drive, select the Down arrow in the Drive field, then select the desired drive letter. After completing your changes, select OK to activate the changes. The Toolkit Information reappears. b. Select the Options pull-down. c. Select Install. d. Follow the prompts in the message boxes to complete the installation. You will swap diskettes several times during installation. The message Install successful on drive x appears under the name of each component at the completion of the installation. Remove the last diskette. Select Options, then Exit. You have successfully installed OS/2 Developer's Toolkit. At this point, you do not need to reboot your system. Go on to the next section to install PL/I for OS/2 Toolkit. ═══ 5.3.2. Installing PL/I for OS/2 Toolkit ═══ To install PL/I for OS/2 Toolkit onto your workstation, do the following: 1. Insert Diskette 1 of 2 into drive A. 2. From an OS/2 window or full-screen, change the current drive to drive A by issuing the following command: a: at the OS/2 command prompt. 3. Type install at the OS/2 command prompt and press Enter. There is a short delay while files are being loaded. The PL/I for OS/2 Toolkit READ.ME file appears. Read this file for the most recent information about PL/I for OS/2 Toolkit. Press Continue to continue, or Cancel to exit. If you press Continue, the PL/I for OS/2 Toolkit Install panel appears. 4. On the Install panel: a. Indicate whether you want the program to update your CONFIG.SYS file automatically. This is recommended if you do not want to manually update your CONFIG.SYS file. If you choose to have your CONFIG.SYS file modified automatically, the installation program first creates a backup copy with the name CONFIG.BAK. Select OK to continue with the installation. b. If you choose not to update your CONFIG.SYS file automatically, a message box appears to tell you that the path information is placed in the CONFIG.ADD file. Select YES to continue with the installation, or NO to return to the previous screen. c. Indicate whether you want to install PL/I for OS/2 Toolkit and new PL/I for OS/2 header files. For a description of these components, select the component and then select the Descriptions button. You may decide that you want to install all of the available options; if so, select Select all to install the entire product. d. Provide the drive and directory in which you want to install the PL/I for OS/2 Toolkit files. By default, they are placed in the C:\PLITK directory. However, if you want to install the files on another drive, select Disk Space, select the appropriate drive onto which you want to install the files, select change directories to selected drive, and then select OK. 5. After you have specified your installation options, select Install or press Enter to proceed. Youdonothavetoinstallalltheoptionsatthispoint .Youcanusetheinstallationprogramagainatanytimetoreinstall ,delete ,orinstalladditionaloptions . 6. If a file with the same name as a backup file exists, a dialog box appears. Choose either to overwrite the existing file, or provide a new file name. Then select OK or press Enter. A window displays the status of the installation program, including which files are being installed and the percentage of the total files that have been installed. 7. When the installation is complete, a message box appears indicating that installation has successfully completed. Select OK to return to the main installation window, and then select EXIT to end the installation program. 8. Reboot your system to use the revised CONFIG.SYS file. If you chose to manually modify your CONFIG.SYS file, see Modifying Your CONFIG.SYS File at this time. ═══ 5.4. Modifying Your CONFIG.SYS File ═══ If you chose to manually update your CONFIG.SYS at installation, the path statements can be found in the CONFIG.ADD file. To update your CONFIG.SYS file manually, do the following: 1. Open your CONFIG.SYS file with a text editor. 2. Make the following changes in your CONFIG.SYS file by adding the following statements to the corresponding path name: Path Name Statement LIBPATH C:\PLITK; IBM.VPLI C:\PLITK; IBM.SYSLIB C:\PLITK\INCLUDE; INCLUDE C:\PLITK\INCLUDE;C:\PLITK; HELP C:\PLITK\HLP; LIB C:\PLITK; 3. Save the modified CONFIG.SYS file and exit the text editor. 4. Close all active programs and system sessions. 5. Reboot your workstation to use the revised CONFIG.SYS file. You have successfully installed PL/I for OS/2 Toolkit on your workstation. ═══ 5.5. Warning on Level of PL/I for OS/2 ═══ If the PMWIN.CPY file in the \IBMPLI\INCLUDE directory is dated: o June 1, 1994 (PL/I for OS/2 Personal Edition, 10H7819), or o June 2, 1994 (PL/I for OS/2 Professional Edition, 10H7848) or earlier Then you must replace the PMWIN.CPY file with the version that comes with PL/I for OS/2 Toolkit: 1. Find the PMWIN.CPN file in the \PLITK\INCLUDE directory. 2. Rename the existing PMWIN.CPY file in the \IBMPLI\INCLUDE directory. 3. Copy PMWIN.CPN (the Visual PL/I version) into the \IBMPLI\INCLUDE directory. 4. Rename PMWIN.CPN to PMWIN.CPY. ═══ 5.6. Starting and Ending Visual PL/I ═══ To start Visual PL/I: 1. Select the Visual PL/I icon from the appropriate Desktop Manager folder. The IBM product panel appears for a moment. When the Visual PL/I folder appears, as shown in A Typical Visual PL/I Folder, you can start using Visual PL/I. A Typical Visual PL/I Folder To end Visual PL/I: 1. Display the Visual PL/I folder. 2. Position the mouse pointer in the window and click mouse button 2 to display the context menu. 3. Select Exit from the context menu to exit Visual PL/I. If you have not saved the contents of a project you are working on, you are prompted to open the project, display the project context menu, and either select Save (to save the project in the Visual PL/I directory) or Save as (to save the project to any of your other directories). All Visual PL/I projects are stored as files with the .PMG file extension. ═══ 5.7. Getting Help ═══ Help for learning how to use Visual PL/I is offered in two ways: o Tutorials o Online help ═══ 5.7.1. Completing the Tutorials ═══ Tutorials at the end of this book are provided to help you use Visual PL/I. You can follow each step and create your own sample application. ═══ 5.7.2. Getting Online Help ═══ While you are working with Visual PL/I, help is available by pressing F1. ═══ 5.7.2.1. Highlighted words ═══ Highlighted words on help windows indicate that additional information is available for this topic. To display the information, double-click on the word. ═══ 5.7.2.2. Pop-up windows ═══ Generally, these windows have a Help push button. Select that push button to display additional information about the active window. To get additional information, select Help from the action bar. Select any of the following: General help Displays general information about the active window. To display extended help, press F2 from any help window. Using help Displays Help for using the help facility. Keys help Displays information about the keys and their functions. Press F9 from any help window to get help for the keys. ═══ 6. Before You Begin Using Visual PL/I ═══ Before you begin working with Visual PL/I, you need to be familiar with its concepts and conventions. This chapter also explains how to set up your environment. ═══ 6.1. Understanding Visual PL/I Concepts ═══ When you create an application with Visual PL/I, it stores the application components, such as windows, menu bars, and controls, into a single project. Projects are represented as icons in the Visual PL/I for OS/2 folder. A Typical Visual PL/I for OS/2 Folder To open a project, double-click mouse button 1 on the project icon. Objects you have created for the project are displayed in the project window as icons. While you would normally keep all the features for a particular interface or application in the same project, you can also use a project to collect objects that are to be shared by several different applications. A context menu provides you with the options available for each object. To display the context menu, select the window or project and press mouse button 2 in the client area. A client area is the open space within a window. For example, An Example of a Context Menu shows the context menu for a project. An Example of a Context Menu ═══ 6.2. Setting Up Your Visual PL/I Environment ═══ Before you begin creating applications with Visual PL/I, you can set the following options: o Select the directory in which all projects are stored by default o Select the compile and link options to be used for all projects by default o Select whether you want your projects to be enabled for National Language Support (NLS) o Identify the editor you will use with Visual PL/I o Select whether you want Visual PL/I to beep when a warning is issued The following sections explain how to define each of these settings. Visual PL/I displays the default settings. ═══ 6.2.1. Selecting a Working Directory for All of Your Projects ═══ You can select the directory to which the code for Visual PL/I projects will be stored by default: 1. Move the mouse pointer into the Visual PL/I for OS/2 folder client area, the open space within the folder. 2. Click mouse button 2 to display the context menu. 3. Select the Open arrow. 4. Select Settings. The Settings notebook appears. 5. Select the Project Directory tab to display the Project Directory page of the notebook, as shown in Project Directory Page of Settings Notebook. Project Directory Page of Settings Notebook 6. Complete the fields as required. 7. Select the system menu icon in the upper left corner of the notebook. Select Close to process your entries in the page and to close the notebook. Or, double-click on the system menu icon. ═══ 6.2.2. Defining Compile and Link Options ═══ To define these settings: 1. Move the mouse pointer into the Visual PL/I folder client area. 2. Click mouse button 2 to display the context menu. 3. Select the Open arrow. 4. Select Settings. The Settings notebook appears. 5. Select the Compile and link tab to display the Compile and Link page of the notebook. Compile and Link Page of Settings Notebook 6. Complete the fields as required, or use the defaults provided. 7. Select the system menu icon in the upper left corner of the notebook. Select Close to process your entries in the page and to close the notebook. Or, double-click on the system menu icon to close. ═══ 6.2.3. Selecting National Language Support (NLS) Options ═══ With Visual PL/I, you can store text strings as constants in a header file. This option is provided for National Language Support (NLS) purposes. All translated material is held in the same location. To create all projects for NLS: 1. Move the mouse pointer into the Visual PL/I folder client area. 2. Click mouse button 2 to display the context menu. 3. Select the Open arrow. 4. Select Settings from the cascaded menu. The Settings notebook appears. 5. Select the NLS notebook tab. The following page appears: NLS Page of Settings Notebook 6. Complete the fields as required. 7. Select the system menu icon in the upper left corner of the notebook. 8. Select Close to process your entries in the page and to close the notebook. ═══ 6.2.4. Defining an Editor to Visual PL/I ═══ You can choose which editor you want to use with Visual PL/I. It must be a Presentation Manager editor, such as epm.exe. To define the editor: 1. Move the mouse pointer into the Visual PL/I folder client area. 2. Click mouse button 2 to display the context menu. 3. Select the Open arrow. 4. Select Settings. The Settings notebook appears. 5. Select the Editor notebook tab. Editor Page of Settings Notebook 6. Type the path and file name, where the editor resides. 7. Select the system menu icon in the upper left corner of the notebook. 8. Select Close to process your entries in the page and to close the notebook. ═══ 6.2.5. Enabling Visual PL/I for Sound ═══ As you work with Visual PL/I, you can enable it for sound. Then, whenever a warning occurs, the system issues a beep to alert you. 1. Move the mouse pointer into the Visual PL/I folder client area. 2. Click mouse button 2 to display the context menu. 3. Select the Open arrow. 4. Select Settings. The Settings notebook appears. 5. Select the Sound notebook tab. Sound Page of Settings Notebook appears. Sound Page of Settings Notebook 6. Complete the fields as required. 7. Select the system menu icon in the upper left corner of the notebook. 8. Select Close to process your entries in the page and to close the notebook. ═══ 7. Designing Your User Interface ═══ This part describes how to design the various items that determine the appearance of an interface and create a working prototype of your application. To create a working application, see Creating a Working Application. ═══ 8. Working with Projects ═══ In Visual PL/I, the term project refers to a set of Presentation Manager (PM) windows and other objects, such as menus and controls. They collectively represent the user interface for all or parts of a PM application. Several applications can share projects. A new application can reuse parts of a project. Each time you begin to design a new application, you should create a new project. Visual PL/I projects are stored as files with the .PMG file extension. These files are saved in a format that only Visual PL/I can interpret. A project can include one or more of the following objects: o Windows o Menus o Dialog boxes o Controls o Online help o Links between controls and windows o Accelerator or shortcut key tables o Threads In addition to holding this collection of objects, a project can also store skeleton windows you can use as models in developing other windows. You can also store skeleton menus. ═══ 8.1. Allowing Multi-Developer Support ═══ Visual PL/I projects are divided into two categories: o DLL project o EXE project A DLL project requires an EXE project to load the windows and dialogs within the project. You cannot run a DLL project on its own. IfyouareunfamiliarwiththesetermsandyouplantouseVisualPL / Itobuildaprototype ,createanEXEproject .IfyouselectDLL ,youcannotrunyourprototypeafteryouhavecompletedtheapplicationdesign .Toworkproperly ,theEXEprojectmustcalltheDLLproject . For applications with more than one developer, it is suggested that one developer work on an EXE project while the others develop DLL projects. The EXE project must contain the main function and should contain at least one primary window with related dialogs. Other developers can then work on various DLL projects. These projects contain dialogs and windows that the main EXE project can call. When the projects are joined together, the final links are put in to call windows and dialogs in DLL projects. When generating DLL projects, use an earlier version of the EXE project to unit test the DLL windows and dialogs. Each developer should use a different project name to ensure unique window procedure names throughout the application. ═══ 8.2. Defining IDs and #define Values for Project Components ═══ Each component of your application must have an identifier and a #define value assigned to it. The identifier and value are stored as #define statements for use by Visual PL/I and the OS/2 resource compiler. These statements are also translated into named constants for use in the PL/I code. As you use Visual PL/I to create these components, you are asked to type an ID number and a #define value for the component. The #define value assigns a resource identification number and a parameter name to the item you created. This information is required for programming purposes. If you do not fill in these two fields, Visual PL/I automatically assigns an ID and a #define value to the control. You cancreateaheaderfileandassignyourown# defineconstantsandIDstoyourproject .Todoso : 1. Click on mouse button 2 to display the project context menu. 2. Select Import from the menu. 3. Select Associate .h file. 4. Associate the file with your project by completing all fields in the Associate .h file pop-up window, or by renaming the file to your project name, using the following format: projectname.pmh The #define combination box is now filled with the constants from your file. For example, for entry fields, the constants prefixed with EF_ will fill the #define combination box. For push buttons, the prefix is PB_. The projectname.pmh file is checked each time the project is opened. ═══ 8.3. Creating a New Project ═══ To create a new project: 1. Start Visual PL/I. The Visual PL/I folder displays icons for all projects that you worked on in the previous Visual PL/I session. If you are opening the folder for the first time, it contains one or more sample applications created using Visual PL/I. 2. Position the mouse pointer in the client area of the Visual PL/I folder and click mouse button 2 to display the context menu. Context Menu 3. Select New from the context menu. The New Project pop-up window is displayed, as shown in New Project Pop-Up Window. New Project Pop-Up Window 4. Type the name you want to assign to your new project. You can type up to eight characters in length for the name. 5. Select whether the project is to generate a DLL or EXE file. YoucannotrunaDLLprojectonitsown .ItrequiresanEXEprojecttoloadthewindowsanddialogswithintheproject . 6. Select the New push button. The new project is created and an icon representing the project is added to the Visual PL/I window, similar to the one shown in Folder Containing the MYPROJ Icon. You can now proceed to define the objects. Folder Containing the MYPROJ Icon ═══ 8.3.1. Representing Projects as Text in the Visual PL/I Folder ═══ As you continue to create and store new projects in Visual PL/I, you will have many icons in the Visual PL/I folder. You can change the presentation of the projects to a text list of project names, rather than having each project represented by an icon. Youcanalsoapplythisoptiontowindowsandmenusrepresentedinaparticularprojectwindow . To create a text list within the Visual PL/I folder: 1. Click mouse button 2 to display the context menu. 2. Select Open. 3. Select Text view. ═══ 8.3.2. Representing Projects as Icons in the Visual PL/I Folder ═══ When you first receive Visual PL/I, projects are represented as icons in the Visual PL/I folder by default. However, if you have changed to text, you can easily change back to icons. To display icons with corresponding text: 1. Click mouse button 2 in the client area of the folder to display the related context menu. 2. Select Open. 3. Select Icon view. ═══ 8.4. Opening an Existing Project ═══ You can open an existing project with one of the following methods: o From the Visual PL/I folder o From the command line ═══ 8.4.1. From the Visual PL/I Folder ═══ Each time you start Visual PL/I, it automatically displays the projects you last worked on. You can use any of them by double-clicking mouse button 1 on the icon. If the projects are stored in another directory and are not currently displayed, do the following: 1. Display the context menu by moving the mouse pointer into the Visual PL/I folder and clicking mouse button 2. 2. Select Load Project... from the context menu to display the Select a .PMG file pop-up window. Select a .PMG File Pop-Up Window This window displays the names of any project files it finds in the directory specified. 3. Select the directory to be searched. 4. Select the project to be opened. 5. Select OK. ═══ 8.4.2. From the Command Line ═══ 1. At the OS/2 command prompt, type VPLI. You can also specify the name of the project you want to open. For example: VPLI proj1.pmg 2. Press Enter. NotethatonlyonecopyofVisualPL / Icanbeexecutingonyourworkstation . ═══ 8.5. Saving a Project ═══ You can save a project at any time and resume working on it later. Saved projects are stored with the .PMG file type. Remember to save your project before you exit. To save a project: 1. Position the mouse pointer in the client area of the project window. Click mouse button 2 to display the project context menu. 2. Select Savefrom the menu. If the project window is open, selecting PF2 also saves the project. The project is saved under its original name that you assigned when you created it. If you want to save the project with a different name, select Save As from the context menu. The Save As pop-up window appears, as shown in Save As Window. The original project name appears as the file name. You can change it by over typing it with the new name. You can also use Save As to copy a project. Save As Window ═══ 8.6. Deleting a Project ═══ To delete a Visual PL/I project: 1. Display the Visual PL/I folder. 2. Select the icon for the project you want to delete. 3. Click mouse button 2 to display the context menu. 4. Select Delete from the context menu. 5. Select From folder from the cascaded menu to remove the project from the Visual PL/I folder, while leaving the project intact on your disk. 6. Select From disk from the cascaded menu to remove all files from the disk. This also removes the project from the Visual PL/I folder. ═══ 8.7. Copying Objects Between Projects ═══ To copy objects, such as windows and menus, from one project to another: 1. Open the project containing the objects you want to copy. 2. Open the project that is to contain the copied objects. 3. Select the appropriate object icon. 4. Press the CTRL key and mouse button 2 at the same time. Drag and drop the object icon into the receiving project window. Release both the CTRL key and mouse button 2. 5. The object is duplicated in the receiving project window. ═══ 8.8. Moving Objects Between Projects ═══ To move objects, such as windows and menus, from one project to another: 1. Open the project containing the objects you want to move. 2. Open the project that is to contain the moved objects. 3. Select the object icon. 4. Press down mouse button 2 and drag and drop the icon onto the receiving project window. Release mouse button 2. 5. The object now appears in the receiving window and disappears from the window that originally contained it. ═══ 8.9. Defining Settings for a Specific Project ═══ In the same way that you defined settings for all of your projects (see Setting Up Your Visual PL/I Environment), you can define settings for a specific project. Any settings that you define for a project override the overall settings you have defined for all projects (in the Visual PL/I folder Settings option). You can define the following settings for a project in the projects notebook: o The project options, which determine whether the project is to be an .EXE or a .DLL file. o The output options for the project, which include: - The files to be written as output files - Whether output windows and menus are written to a .DLG file o The compile and link options, which include: - The link command to be used - The library to be used for the project - The compile options to be used - The stack size - Other object files to be used with the project o The drive and path of the project directory o Whether or not you want to use a grid to help you design your project windows. o If you are working on a LAN, the database you want to work with. The following sections provide step-by-step instructions on how to complete each notebook page. ═══ 8.10. Setting Project Options ═══ To set project options for your project: 1. Open the project window by positioning the mouse pointer on the project icon and clicking on mouse button 2. 2. Select Open. The project window appears. 3. Click on mouse button 2 in the client area of the project window. 4. Select the Open arrow. 5. Select Settings. The Project Settings notebook and the Project Options page within the notebook appear. Project Options Page of the Project Settings Notebook 6. Select whether the project is to be an .EXE or a .DLL file. Choose .EXE if you are creating a prototype. 7. Click on the system menu icon in the upper left corner of the window and select Close. Your selections are saved and the notebook is closed. ═══ 8.11. Setting Output Options ═══ To set output options for your project: 1. Open the Project Settings notebook by positioning the mouse pointer on the project icon and clicking mouse button 2. 2. Select Open. The project window appears. 3. Click on mouse button 2 in the client area of the project window. 4. Select the Open arrow. 5. Select Settings. The Project Settings notebook appears. 6. Select the Output Options tab to display the notebook page as shown in Output Options Page of the Project Settings Notebook. Output Options Page of the Project Settings Notebook 7. Choose which files are to be written as output files. Click on the check box to select or deselect a file. 8. Select whether output windows and menus should be written to a .DLG file. 9. Click on the system menu icon in the upper left corner of the window and select Close. Your selections are saved and the notebook is closed. ═══ 8.12. Setting Compile and Link Options ═══ To set the compile and link options for your project: 1. Open the Project Settings notebook by positioning the mouse pointer on the project icon and clicking mouse button 2. 2. Select Open. The project window appears. 3. Click on mouse button 2 in the client area of the project window. 4. Select the Open arrow. 5. Select Settings. The Project Settings notebook appears. 6. Select the Compile and Link tab to display the Compile & Link notebook page, as shown in Compile and Link Notebook Page. Compile and Link Notebook Page 7. If you want to change the link command, type the new command. 8. If you want to select a new library for use with your project, type the new library name. 9. Type any new compile options to be used, if necessary. 10. Change the stack size to be used for your project, if necessary. 11. List any other object files to be used with the project. 12. Select the System Menu in the upper left corner of the notebook. 13. Select Close to process your entries and close the notebook. ═══ 8.13. Setting the Drive and Path for Your Project Directory ═══ To set the drive and path of the working directory that contains the project: 1. Select the project icon in the Visual PL/I folder. 2. Click mouse button 2 to display the context menu. 3. Select Open. The project window appears. 4. Click mouse button 2 to display the context menu of the project window. 5. Select the Open arrow. 6. Select Settings. The Project Settings notebook appears. 7. Select the Project directory page from the Project Settings Notebook. The window shown in Project Directory Page of the Settings Notebook appears. 8. If the drive and path are correct, select Close from the system menu icon. 9. If you change the drive and path, type the correct directory. Select Close from the system menu icon to set the working directory for the project. Project Directory Page of the Settings Notebook ═══ 8.14. Creating a Grid on Your Project Windows ═══ As you design your windows, Visual PL/I has several design tools available to help you create attractive and professional-looking windows. One of these options is the use of a grid to help you with the placement of controls. To set up grids on your project windows: 1. Select the project icon in the Visual PL/I folder. 2. Click mouse button 2 to display the context menu. 3. Select Open. The project window appears. 4. Click mouse button 2 to display the context menu of the project window. 5. Select the Open arrow. 6. Select Settings. The Project Settings notebook appears. 7. Select the Grid tab in the notebook to display the Grids notebook page, as shown in Grids Page in the Settings Notebook. Grids Page in the Settings Notebook 8. Your options on this window are as follows: ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 1. Grid Options │ ├────────────────────┬─────────────────────────────────────────────────────────┤ │ OPTION │ DESCRIPTION │ ├────────────────────┼─────────────────────────────────────────────────────────┤ │ GRID │ Select this option to create a grid on the windows. If │ │ │ you select this option, size the grid by typing an X │ │ │ and Y coordinate in the corresponding entry fields in │ │ │ this notebook. The larger the number entered, the more │ │ │ distance between the grid marks. │ ├────────────────────┼─────────────────────────────────────────────────────────┤ │ SNAP │ This option allows you to move a control icon into a │ │ │ window. Visual PL/I automatically positions it at the │ │ │ next horizontal grid mark in the window. You can still │ │ │ size it vertically. │ ├────────────────────┼─────────────────────────────────────────────────────────┤ │ SNAP WIDTH │ Select this option to have Visual PL/I automatically │ │ │ position the control both vertically and horizontally │ │ │ in the window. │ └────────────────────┴─────────────────────────────────────────────────────────┘ Table 1. Grid Options 9. Select the system menu in the upper left corner of the window. 10. Select Close to process your entries. When you open any window, it contains a grid. ═══ 9. Designing Windows ═══ This chapter takes you through each of the steps required to: o Create a window o Move a window o Change window measurements o Change window attributes o Change the style of a window o Copy a window o Display, hide, or delete windows o Select the color and font for a window ═══ 9.1. Creating a New Window ═══ To create a new window: 1. Open the Project window. 2. Click on mouse button 2 to display the context menu of the project window. 3. Select New from the menu. 4. Select Window from the cascaded menu to display the New Window pop-up. New Window Pop-Up 5. In the Reference name field, type the name you want to assign to the window. Give each window a unique and meaningful name. This name also serves as the identifier for the icon representing this window in the project window. 6. Type the window title in the Title bar text entry field. The title appears in the title bar of the new window when it is displayed. 7. You can select any menu bar that has already been defined in the project from the menus list box and attach it to the window being created. If no menu bars have been defined in the project, the default of No Menubar is selected. 8. To define the type of window you want to create, select one of the following from Window type group box, as shown in Window Types. ┌────────────────────────────────────┬─────────────────────────────────────────┐ │ WINDOW TYPE │ DESCRIPTION │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ PRIMARY WINDOW │ A movable and resizable window in which │ │ │ you present the objects and actions of │ │ │ your application. Every application │ │ │ has a primary window. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ SECONDARY WINDOW │ A movable and resizable window that is │ │ │ always associated with a primary │ │ │ window. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ DIALOG BOX │ A movable, fixed-size window in which │ │ │ you ask users for information required │ │ │ to complete an action. A dialog box is │ │ │ associated with another window. │ └────────────────────────────────────┴─────────────────────────────────────────┘ Table 2. Window Types 9. You can specify the following characteristics of the window in the Window Styles group box, as shown in Window Characteristics. ┌─────────────────────────────────┬────────────────────────────────────────────┐ │ WINDOW STYLE │ DESCRIPTION │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ TITLE BAR │ The area at the top of a window that con- │ │ │ tains its title. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ SYSTEM MENU │ A pull-down menu in the top left-hand │ │ │ corner of the window that you can use to │ │ │ restore, move, resize, minimize, and maxi- │ │ │ mize the window. It allows you either to │ │ │ end the application or to close the │ │ │ window, depending on whether the window is │ │ │ the primary window or a secondary window. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ MINIMIZE │ A component in the top right-hand corner │ │ │ of the window that removes the window and │ │ │ places an application-defined icon on the │ │ │ screen. You can select the ICON push │ │ │ button to associate an icon of your choice │ │ │ with the window. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ MAXIMIZE │ A component in the top right-hand corner │ │ │ of the window that enlarges the window to │ │ │ the largest possible size, the size of the │ │ │ screen. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ HORIZONTAL SCROLL BAR │ A window component associated with a hori- │ │ │ zontal scrollable area that provides you │ │ │ with a visual clue that more information │ │ │ is available and that the unseen informa- │ │ │ tion can be brought into view. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ VERTICAL SCROLL BAR │ A window component associated with a ver- │ │ │ tical scrollable area that provides you │ │ │ with a visual clue that more information │ │ │ is available and that the unseen informa- │ │ │ tion can be brought into view. │ ├─────────────────────────────────┼────────────────────────────────────────────┤ │ SHELL POSITION │ This option allows OS/2 to position the │ │ │ first window in the application relative │ │ │ to other applications that are already │ │ │ running. │ └─────────────────────────────────┴────────────────────────────────────────────┘ Table 3. Window Characteristics Select as many of these options as you wish to include in the window. 10. The Border styles you can select for the window are as follows. Select one option only, as shown in Border Options. ┌──────────────────────────┬───────────────────────────────────────────────────┐ │ BORDER STYLE │ DESCRIPTION │ ├──────────────────────────┼───────────────────────────────────────────────────┤ │ NO BORDER │ No border type selected. │ ├──────────────────────────┼───────────────────────────────────────────────────┤ │ LINE BORDER │ Thin line around the frame. │ ├──────────────────────────┼───────────────────────────────────────────────────┤ │ DIALOG BORDER │ Default border for a dialog box. │ ├──────────────────────────┼───────────────────────────────────────────────────┤ │ SIZABLE BORDER │ Default border for a resizable window. │ └──────────────────────────┴───────────────────────────────────────────────────┘ Table 4. Border Options 11. If desired, type a number in the ID field and a name in the #define field. These #define values are used to assign a resource identification number and a parameter name for programming purposes. If you do not fill in these fields, Visual PL/I automatically assigns an ID value and a #define name to the window. See Defining IDs and #define Values for Project Components for more information. 12. To return all settings to their defaults, select the Reset push button. To select an icon to represent the window when it is minimized, select the Icon push button to display a pop-up window. Select an icon from those currently available or load a new icon into Visual PL/I. See Adding or Replacing Your Own Icons for details. To save the window, select OK. The saved window is represented by a window icon and the name you typed in the name field. ═══ 9.2. Moving a Window ═══ If the window has a title bar: 1. Move the arrow pointer over the title bar. 2. Hold down mouse button 1. 3. Move the pointer to the new position and release the button. If the window has no title bar: 1. Move the pointer over the client area of the window. 2. Click on mouse button 1. 3. When the pointer changes shape, hold down the button, move the window to the new position, and release the button. The window is redrawn at its new position. ═══ 9.3. Changing Measurements for a Window ═══ You can set both the position and the size of a window as you work with it. To change window measurements: 1. Select the window to be changed. 2. Display the context menu for the window. 3. Select Position/size from the context menu. The Position/Size pop-up window appears. Position/Size Pop-Up Window 4. Change the following fields as required: o The X position relates to the position of the window on the X axis. o The Y position field relates to the position of the window on the Y axis. o The X size relates to the length of the window on the X axis. o The Y size relates to the length of the window on the Y axis. 5. Select OK. The window is repositioned or resized. To quicklysizeawindow : 1. Move the cursor over the border until it changes shape to a double-arrowed pointer. 2. Hold down mouse button 1. 3. Move the pointer to the new position and release the button. The window redraws itself to the new size. If the window is not resizable, Presentation Manager does not normally let you resize it. However, with Visual PL/I you can resize it as follows: 1. Position the pointer just inside the border. 2. Hold down mouse button 1. 3. Move the pointer to the new position and release the button. The window is redrawn with its border in the new position. ═══ 9.4. Changing the Attributes of a Window ═══ To change the attributes you have assigned to a window: 1. Select the icon or name in the project window that represents the window you want to change. 2. Click mouse button 2 to display the context menu. 3. Select Change from the context menu. The Change Window pop-up appears, as shown in Change Window Pop-Up. You can now change any of these attributes. Change Window Pop-Up 4. Change any of the attributes displayed in the window and select OK to process your entries. See Creating a New Window. ═══ 9.5. Changing Window Style ═══ You can specify characteristics for an existing window. To display the characteristics available: 1. Select the icon representing the window you wish to work on. 2. Display the context menu. 3. Select Styles from the menu. The Window Styles pop-up window appears, as shown in Window Styles Pop-Up Window. Window Styles Pop-Up Window 4. Select an entry from the WS_Styles list to define the appearance or behavior of the window. For example, WS_MAXIMIZED creates a maximized window. 5. Select an item from the Item Styles list to define other characteristics of a window. For example, FCF_TASKLIST adds the window title to the switch list on the OS/2 Task Manager window. For more information on these options, see Presentation Manager Programming Reference. ═══ 9.6. Copying Windows ═══ Visual PL/I has options available that let you: o Copy a window within a project o Copy a window from one project to another project The following sections provide instructions on how to complete each of these activities. ═══ 9.6.1. Copying a Window Within a Project ═══ To create a copy of a window in the same project: 1. Select the icon or name of the window you wish to copy. 2. Display the context menu. 3. Select Copy from the menu. A copy of the window is created and represented by an icon with the number 1 added to the original window name. Change the name of the new window immediately in order to avoid confusion. A quickmethodofcopyingawindowis : 1. Select the window icon. 2. Position the mouse pointer on the icon and press the CTRL key and mouse button 2 at the same time. Move the mouse pointer into the client area and release the mouse button and the CTRL key. A copy of the window is added to the project window. The copy has a number added to the end of the window identifier. Each time you make a copy of the window, this number is incremented by one digit. ═══ 9.6.2. Copying a Window From One Project to Another ═══ To copy a window from one project to another project: 1. Open both projects. 2. Select the icon representing the window you want to copy. 3. Press the CTRL key and mouse button 2 simultaneously and drag and drop the window icon into the client area of the other project. ═══ 9.7. Displaying and Hiding Windows ═══ Windows that are currently available in your Visual PL/I project are represented by icons in the project window. When a window is in an icon format, it is referred to as a hidden window. As you work with Visual PL/I, you can display and hide windows in your project as necessary. ═══ 9.7.1. Hiding A Single Window ═══ To hide a single window: 1. Place the mouse pointer on the open window. 2. Click mouse button 2 on the window. 3. Select Hide from the cascaded menu. The window is reduced to an icon in the project window. ═══ 9.7.2. Showing or Hiding All Windows ═══ To display all windows that reside in a selected project: 1. Open the project. 2. Display the context menu. 3. Select Windows from the menu. 4. To open all windows in the project, select Show all from the cascaded menu. All windows currently in the project are opened and displayed on your screen. To hide all windows in the project, select Hide all from the cascaded menu. All windows currently in the project are reduced to icons in the project window. ═══ 9.8. Deleting a Window from a Project ═══ To delete a window: 1. In the project window, select the icon representing the window to be deleted. 2. Display the context menu. 3. Select Delete. The window is deleted from the project. ═══ 9.9. Setting Color and Font for a Window ═══ You can change the appearance of all controls within a window, such as the foreground or background color, font name, or size. 1. Using mouse button 2, click on the client area of the project window to change the appearance of all controls in the window. 2. From the context menu, select Pres Params (presentation parameters). The Settings pop-up window appears, as shown in Settings Pop-Up Window. Settings Pop-Up Window 3. Set the presentation parameters as required and select OK to process your entries. You can set colors in either of these two ways: o By using RGB (red, green, blue) values o By using the color indexes offered by Visual PL/I ═══ 9.9.1. Using RGB Values to Set Window Color ═══ To use RGB values to change the color of controls in a window: 1. Select the appropriate control in the window. 2. Select an item from the list of presentation parameters. For example, to change the background color of a control, select BACKGROUNDCOLOR. 3. Display the Set Presentation Parameters window. The red, green, and blue values range from 0-255. Calculate a single RGB value by using the following formula: RGB= Red*65536 + Green*256 + Blue 4. Type the RGB value in the Enter Presentation Parameters settings entry field. For example, if the RGB value of the color is 1234567, type that number. 5. Select Add to type your selection in the Selected Parameters list box. 6. Select OK to apply the change to the selected control or window. ═══ 9.9.2. Using Color Indexes ═══ To set the color parameters by using the Visual PL/I color indexes: 1. Select an Index parameter from the Presentation Parameters list. For example, BACKGROUNDCOLORINDEX or FOREGROUNDCOLORINDEX. 2. Select a color from the group of color indexes. ThecolorindexesvaluesetworkonlywhenappliedtoanIndexparameter .Forexample ,tochangethebackgroundcolorofacontroltored ,selectBACKGROUNDCOLORINDEXfromthePresentationParameterslistandselectthecolorfromthecolorindexesvalueset . 3. Select Add to add your selection to the Selected Parameters list. 4. Select OK to apply the change to the selected control or window. ═══ 9.9.3. Changing Fonts ═══ To change the font in a window: 1. Display the Set Presentation Parameters pop-up window. 2. Select the presentation parameter to apply the new font. For example, select FONTNAMESIZE. 3. Select the FONTNAMESIZE option from the Presentation Parameters list. Scroll through the Fonts list until you find the font you want to use. For example, 14.Tms Rmn. 4. Select the Add push button and your selection appears in the Selected Parameters list. 5. Select OK to apply this change to the selected control or window. ═══ 9.9.4. Changing Color or Font Settings ═══ To change the color or font settings, you must first `unset' these parameters before you can set new ones. 1. Open the Settings window. 2. Select the presentation parameter you wish to change, by selecting the current color or font from the Selected Presentation Parameters list. 3. Select the Remove push button to delete the entry from the Selected Presentation Parameters list and return it to the Presentation Parameters list. 4. Set new presentation parameters as before or select OK to return to the active window. ═══ 10. Designing Menus ═══ Menus are the means by which users can select the various options available to them within a product. Menus provide you with a logical method of ordering and layering all actions to be performed by the application user. In Visual PL/I, main menus are divided into two categories: o Menu bars o Pop-up menus Also in this chapter, you learn how to: o Create pull-down menus and cascaded menus o Make changes to a menu o Copy a menu - Within the same project - To a different project o Delete a menu o Create a pop-up menu ═══ 10.1. Menu bar ═══ This is an area at the top of a window that contains action keywords. These keywords provide users with access to specific actions either for a window or any of its associated windows. For each item in the menu, you can create a sub-level of actions or additional keywords and display them in a pull-down menu associated with that menu item. ═══ 10.2. Pull-down menu ═══ This can have a cascaded menu, which contains a set of choices directly related to the pull-down selection. ═══ 10.3. Pop-up menu ═══ This contains action keywords, with the option of adding associated pull-down menus and cascaded menus. The only difference in the two is the presentation of the information. ═══ 10.4. Selecting a Menu Type ═══ When you design menus with Visual PL/I, you can create either: o Menu bar, which appears across the top of your window and has associated pull-down menus attached to each keyword in the menu. o Pop-up menus, such as the context menus, that are displayed when the user clicks on the mouse button. ═══ 10.5. Creating a New Menu ═══ To create a new menu: 1. Open the project. 2. Position the mouse pointer within the project window and click mouse button 2. A list of menu options appears. 3. Select New from the menu. 4. Select Menu from the New cascade. The Menu pop-up window appears, as shown in New Menu Pop-Up. New Menu Pop-Up 5. In the Reference entry field, type a unique reference name for the new menu item. 6. Select whether the menu appears to the user as a menu bar, or a pop-up menu item. 7. If necessary, assign the #define values to the items you are adding to a menu, by typing a number in the ID field and a value in the #define field. The #define values are used to assign a resource identification number and a parameter name for programming purposes. If you do not use this option, Visual PL/I automatically assigns an ID value and a #define name. See Defining IDs and #define Values for Project Components for more information. 8. Select a menu icon (that you have already created) from the project window and open it. The Menu pop-up window appears. 9. Note that the Indentation Level slider is located at level 1. All text you type in while the slider is in this position appears in the action bar. Later, when you add pull-down options for each text item in the menu bar, move the slider one position to the right to level 2. For cascaded menu entries for each pull-down menu item, move the slider to the right to level 3. 10. If items already are displayed in the menu selection list shown in the lower left of the window, select the menu item, pull-down item, or cascade item you want your menu item to follow. Move the Indentation Level one position to the right. 11. Type the name of the new menu item in the Menu Text entry field. If you want the first character of the action name to be used as a keyboard shortcut key for the action, precede it with a tilde character (~). For example, ~File, ~Open, and ~Exit. The text is displayed in the menu with the first character underscored. 12. To add the menu item to the list in the menu pop-up window, either select Add or press the Enter key. ═══ 10.6. Adding a Pull-Down Menu ═══ After creating the text to be displayed in the menu bar, add a pull-down menu containing the various user options available from each action item displayed in the menu bar. To add a pull-down for a menu item: 1. Select the menu item to which you want to attach the pull-down, or the pull-down item you want your pull-down item to follow. 2. Select level 2 on the Indentation Level slider. 3. Type the text of the pull-down item in the Menu Text entry field. 4. Select Add to add the pull-down item to the list in the menu pop-up window. ═══ 10.7. Adding a Cascaded Menu ═══ Each item on a pull-down menu can have its own cascaded menu. This menu contains a set of choices that are related to the pull-down option. Use this type of menu to reduce the length of a menu. To add a cascade item to a pull-down or a cascade: 1. Select the pull-down item or cascade item you want your cascade item to follow. 2. Move the Indentation Level slider one position to the right. 3. Type the text of the cascade item being added into the Menu Text entry field. 4. Select Add to add the cascade item to the menu. The entry appears on the list in the menu pop-up window. ═══ 10.8. Adding a Separator ═══ In Visual PL/I, a separator is a visual cue, such as a line, that provides a visual distinction between two adjacent lines. You can add a separator to visually divide pull-down items or cascade items. The separating line is inserted between the two items. To add a separator: 1. From the list, select the item you want the separator to follow. 2. Select the Separator push button. The separator is added to the pull-down or cascade, directly following the item you selected. ═══ 10.9. Editing a Menu Entry ═══ You can edit the text for a menu, pull-down, or cascade item within the menu pop-up window. To edit an item: 1. Select the item in the selection list that is to be changed. 2. Type the new text in the Type item entry field. 3. Select Edit to update the item with the new text. ═══ 10.10. Moving a Menu Entry ═══ To rearrange items in a menu: 1. Select a menu item to move down. 2. Select Move. The item is exchanged with the item immediately below. ═══ 10.11. Deleting Items from a Menu ═══ To delete an item from a menu bar: 1. Select the appropriate menu bar icon from the project window and open it. The Menu Bar pop-up window appears. 2. Select the menu item to be deleted from the selection list. 3. Select Delete. This action immediately deletes the item selected from the list in the menu pop-up window. Ifyouselectamenuitemfordeletion ,andthenselectDelete ,youalsodeleteallpull - downitemsandcascadeitemsthatbelongtothemenuitem .Ifyouselectapull - downitemfordeletion ,andthenselectDelete ,youalsodeleteallthecascadeitemsthatbelongtothepull - downitem . ═══ 10.12. Changing the Color and Font for Menu Items ═══ To change the color and font used in a menu: 1. Select the appropriate menu icon from the project window and open it. The Menu pop-up window appears. 2. Select the Color and font push button at the bottom of the Menu pop-up window. The Settings pop-up window appears, as shown in Settings Pop-Up Window. Settings Pop-Up Window 3. To change the menu color: o Select a color from the Color Indexes group, clicking on the color block with mouse button 1. o Select the Presentation parameters to be used. o Select Add or Remove. 4. To change the menu font: o Select a font from the Type field. Use the Down arrow to display a list of all available fonts. Note that an example of each font type is displayed in the Font area as you select it. When you select a font, the new font type appears in the Presentation Parameter Value field. o Select Add or Remove. 5. Select OK. ═══ 10.13. Setting the Attributes and Styles of a Menu Item ═══ Menu attributes specify the initial settings for a menu item. The status can change frequently during the execution of a program. For example, MIA_CHECKED controls whether a check mark (/) appears next to the item. Action bar styles determine the specific look of the menu bar. For example, MIS_BREAK defines a menu bar pull-down with two columns. To set these two characteristics of a menu bar: 1. Click on mouse button 2 on a project icon in the Project window. 2. Select Change. 3. The Menu in... pop-up window appears. 4. Select the Attributes push button on the right side of the Menu in... pop-up window. The Action Bar Attributes & Styles pop-up window appears. Attributes and Styles Pop-Up Window 5. Select the attribute and style you want to use as the initial setting for the menu item. 6. Select OK. ═══ 10.14. Changing a Menu ═══ To change a menu: 1. Select the menu icon from within the project window. 2. Display the context menu. 3. Select Change... from the menu. The Change a Menu pop-up window appears. This window is identical to the Add a Menu window. Change the features of the menu in this window as required. 4. Select OK. ═══ 10.15. Copying a Menu ═══ You can make a copy of a menu that is already available within a project. You can use copies within the project, or copy it from one project into another one. ═══ 10.15.1. Copying a Menu Bar Within a Project ═══ To make a copy of a menu bar for later use in your project: 1. Select the menu bar you wish to copy. 2. Press the Ctrl key, and while holding it down, use mouse button 2 to drag and drop the menu bar into the project window that is to contain it. 3. Release the Ctrl key and the mouse button. A copy of the menu bar is displayed in the project window. Each time you copy a menu, Visual PL/I automatically adds a number to it, incrementing the number by one each time the menu is copied. To copy the menu directly into a specific window: 1. Open the window the menu is to be associated with. 2. Drag and drop the menu directly into the window. Any later changes you make to the menu is made in the associated window as well. ═══ 10.15.2. Copying a Menu to Another Project ═══ To copy a menu to another project: 1. Open the project that you want to copy the menu into. 2. Open the project containing the menu you want to copy. 3. Select the menu, by clicking mouse button 1 on it. 4. Press the Ctrl key, and while holding it down, use mouse button 2 to drag and drop the menu from one project window into the other. 5. Release the Ctrl key and the mouse button. A copy of the menu appears in the project window. Be sureyouholddowntheCtrlkeywhenyoucopyamenu .IftheCtrlkeyisnothelddown ,themenuismoved ,notcopied . ═══ 10.16. Deleting a Menu ═══ To delete a menu: 1. Select the menu to be deleted from the project window. 2. Display the context menu. 3. Select Delete from the menu. The menu is deleted from the project. ═══ 10.17. Creating a Pop-Up Menu ═══ To create a pop-up menu: 1. Open the project. 2. Position the mouse pointer within the project window and click mouse button 2. A list of menu options appears. 3. Select New from the menu. 4. Select Menu from the New cascade. The Menu pop-up window appears, as shown in Menu Pop-Up Window. Menu Pop-Up Window 5. In the Reference entry field, type a unique reference name for the new menu item. 6. Select Popup in the Menu type group box. The Define Pop-Up Details window appears. 7. If necessary, assign the #define value for the pop-up menu by typing in the ID field and a value in the #define field. If you do not use this option, Visual PL/I automatically assigns an ID value and a #define name. See Defining IDs and #define Values for Project Components. ═══ 11. Adding Controls, Icons, and Bitmaps ═══ This chapter explains how to add controls, icons, and bitmaps to your applications. The first part of this chapter describes how to use the Objects toolbox to add these objects to your application. The second part of this chapter contains step-by-step instructions on how to add each type of control and tailor it to your requirements. In addition to the information provided in this chapter, you may want to refer to Object-Oriented Design: IBM Common User Access Guidelines for further details on controls. ═══ 11.1. Controls-An Overview ═══ The controls in a window provide users with the means to make choices and type in information. You can use controls to present a complicated array of options and suboptions in a way that is easy for the user to understand. Controls usually contain text. Examples include labels in push buttons or field prompts. The controls that you can create with Visual PL/I are divided into different types of objects, according to their purpose. They are grouped together in an Objects toolbox, as shown in Visual PL/I for OS/2 Objects Toolbox. Visual PL/I for OS/2 Objects Toolbox The objects toolbox automatically appears when you begin working on the first window of your new application. Double-click on the project you want to work with in the Project window. As you point to an object in the toolbox with the mouse pointer, the name of the object is displayed in the space located at the bottom of the toolbox. Choose the type of control you want to add to your application, and drag it into the appropriate window. From this point, you are directed through a series of windows and dialogs that help you define the control exactly as you want it. ═══ 11.2. Adding Controls ═══ To add a control to a window: 1. Move the mouse pointer into the toolbox. 2. Press and hold down mouse button 2 on the icon you want to move into a project window. 3. Drag and drop the icon for the required control or object from the Objects toolbox into the window. Release mouse button 2. The pop-up window associated with the icon you selected appears. In this window, define the attributes required to create the control. 4. After you fill in the window, select OK to save your entries and display the resulting control in the window. ═══ 11.3. Adding an Entry Field ═══ An entry field is a two-part control consisting of text and a rectangular box into which users can type one or more lines of text. If more information is available than is currently visible, users can scroll the entry fields. An entry field is either a single-line (SLE) entry field or a multi-line entry (MLE) field. The information in this section explains how to add both types of fields to your application. ═══ 11.3.1. Adding a Single-Line Entry Field ═══ 1. Select the Entry Field icon in the Objects toolbox and drag it into the window. The Entry Field Options pop-up window appears. Entry Field Options Pop-Up Window 2. If you want data to automatically appear in this entry field each time the window is opened, type the data in the Default field. 3. In the Maximum Size field, define the maximum number of characters to be typed in the entry field. 4. Select the Options entry field. If you want a border around the entry field, select the Margin check box. If you want the entry field to automatically scroll when the data typed by the user takes up more space than the visible part of the entry field, select the Autoscroll check box. 5. If you are creating your own IDs and # defines, type this information in the ID and #define fields. If you do not make entries in these fields, Visual PL/I automatically generates these IDs and #defines for you. See Defining IDs and #define Values for Project Components. 6. Select what Alignment the data will have that the user types in the entry field. Typed data is either left-aligned, right-aligned, or centered. 7. Use the Naming options group box to define the entry field's variable name. 8. Use the Variable Typegroup box to specify whether the entry field is declared as a global, or a local variable. If you select global, the variable is available throughout the application. 9. The list box in the lower right of this pop-up window provides data type options for future releases of Visual PL/I. The data type is currently fixed at CHAR. ═══ 11.3.2. Adding a Multi-Line Entry Field (MLE) ═══ A multi-line entry field (MLE) is an entry field that allows a user to type more than one line of information. 1. Select the MLE icon in the Objects toolbox and drag it into the window. The Multiple Line Entry Field Type pop-up window appears. Multiple Line Entry Field Type Pop-Up Window 2. Select one or more of the check boxes, as shown in Attributes for Multi-Line Entry. ┌────────────────────────────────────┬─────────────────────────────────────────┐ │ ATTRIBUTE │ DESCRIPTION │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ BORDER │ Creates a border around the entry │ │ │ field. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ READ ONLY │ User cannot change the text in the │ │ │ entry field. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ WORD WRAP │ Automatically moves the text in the │ │ │ entry field to the next line as space │ │ │ is used up in a line. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ HORIZONTAL SCROLLBAR │ The entry field can be scrolled hor- │ │ │ izontally. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ VERTICAL SCROLLBAR │ Scrolls the entry field to the left or │ │ │ right. │ ├────────────────────────────────────┼─────────────────────────────────────────┤ │ IGNORE TABS │ Ignores tabs in the entry field, if │ │ │ tabs are set in the window. │ └────────────────────────────────────┴─────────────────────────────────────────┘ Table 5. Attributes for Multi-Line Entry 3. Select the Attributes for the multiple entry field. ═══ 11.4. Adding a Combination Box ═══ A combination box is a control that combines the capabilities of an entry field and a list box. 1. Select the Combination Box icon from the Objects toolbox and drag it into the window. The Combination Box Type window appears. Combination Box Type Window 2. Select one of the following types of combination box: o Combination box - a control that combines the capabilities of an entry field or a list box. o Drop-down combination box - a list hidden until the user takes an action to make it visible. o Drop-down list - a variation of a list box. A drop-down list only displays one item until the user takes an action to display the other objects or choices. 3. Type the text in the Current text field. This text is the current entry in the combination box when it is displayed. 4. If you are assigning your own IDs and # defines, type this information in the related fields. See Defining IDs and #define Values for Project Components. 5. Select OK. ═══ 11.5. Adding Radio Buttons or Push Buttons ═══ You can add two types of buttons to your application window: o Radio buttons o Push buttons To add a radio button or a push button to a window: 1. Select the Buttons icon from the Objects toolbox and use the drag and drop option to place it in your window. The Button Controls pop-up window appears. Button Controls Pop-Up Window 2. If you want to display text within the button, type the text in the Button text entry field. 3. Select the type of button you want to use in the window. In addition to the buttons already described earlier in this section, you can add: o An auto radio button, which is filled in automatically when a user selects it. When the radio button is not automatic, you can control what happens when the user selects it. o A 3 state check box is identical to a check box (see Adding Check Boxes), except that its check box can be half-toned as well as checked or unchecked. It has three distinct states. o An auto 3 state check box automatically toggles its state when the user clicks on it, but you must insert code to change the state of a regular 3 state check box. o A user-defined button, which gives you the option of defining the appearance of a push button. 4. Select OK. ═══ 11.6. Adding an Icon/Bitmap Button to a Window ═══ You can add push buttons to your application in the form of icons and bitmaps. 1. Select the Icon Button icon from the Objects toolbox and drag and drop it into the window in which you would like the button to appear. The Button Icon/Bitmap pop-up window appears. Button Icon/Bitmap Pop-Up Window 2. Either: o Type the name of the icon or bitmap file that you want to make into a push button. If you type the name of a bitmap, select the Bitmap check box. or o Select Files to see a list of icons available on the system. 3. Select the icon button or bitmap you want to add. You can move the icon button or change the color and font as you wish. 4. Select OK. The bitmap or icon appears as a push button in your application. ═══ 11.7. Adding Check Boxes ═══ A check box allows users to turn on or off an option, like a switch. 1. Select the Check Box icon from the Objects toolbox. Drag and drop the icon into the window to which the check box is to be added. The Check Box Controls pop-up window appears. Check Box Controls Pop-Up Window 2. If you want to display text to the right of a check box, type the text in the Button text entry field. 3. Select the type of check box you want to add to the window. When a user selects an auto check box, Visual PL/I automatically checks it. When the check box is not automatic, you can control what happens when the user selects it. 4. Select OK. ═══ 11.8. Adding a List Box ═══ A list box offers users a scrollable list from which they can make a choice. 1. Select the List Box icon from the Objects toolbox. Drag and drop the icon into the window to which the list box is to be added. The List Box #define pop-up window appears. List Box #define Pop-Up Window 2. If you want to define your own ID and # define value for this list box, type the data in the respective fields. If you make no entries in these two fields, Visual PL/I automatically assigns an ID and a #define to the object you just created. See Defining IDs and #define Values for Project Components. 3. Select OK. ═══ 11.9. Adding a Spin Button ═══ A spin button enables you to complete an entry field by scrolling through a ring of related choices. 1. Select the Spin Button icon from the Objects toolbox. Drag and drop the icon into the window to which the list box is to be added. The Spin Button Control pop-up window appears. Spin Button Control Pop-Up Window 2. In the Spin Button type group box, specify whether the spin button is a master button or a servant button. Master buttons have spin arrows and servant buttons do not. One example of the use of both types might be the setting of hours and minutes. You can use a master button to set the minutes, and the servant button to set the hour. Use servant buttons in conjunction with a master button. The button that spins, the master button, is the last button selected. 3. Each attribute that you check in the Style list is associated with the spin button being added to the window. 4. Checked attributes in the Style list are associated with the spin button being added to the window. If you check the Numeric style option, you must define both an Upper limit and a Lower limit for the Numeric range within the spin button. 5. Select the type of Alignment you require. The options are as follows: o Default alignment sets the contents of the spin button to the current OS/2 defaults. o Center alignment centers the contents of the spin button. o Left alignment sets the contents of the spin button to the left. o Right alignment sets the contents of the spin button to the right. 6. Select the Default contents push button to display the Spin Button-Add Default Contents pop-up window, shown in Spin Button - Add Default Contents Pop-Up Window. In this window, you can type in the sequence of text to be displayed, for example, the months of the year. Spin Button - Add Default Contents Pop-Up Window 7. If you are assigning your own IDs and # define values, type these values. See Defining IDs and #define Values for Project Components. 8. Select OK. ═══ 11.10. Adding a Slider ═══ 1. Select the Slider icon from the Objects toolbox. Drag and drop the icon into the window to which the value set is to be added. The Slider Button Controls pop-up window appears. Slider Button Controls Window 2. In the Display slider group box, specify whether the slider is to be positioned horizontally or vertically. 3. In the Slider type group box, indicate the type of slider you want to create: o Snap to increment allows the user to select a value to the nearest gradation line. o Ribbon strip indicates that the slider shaft colors behind the button as the button moves along. o Read only indicates that the slider is used only to display values. 4. Use the Start at group box to indicate the position of the arm (home position). 5. Use the Place slider group box to indicate the position of the slider shaft. It is either left, right, or center for a horizontal slider; and bottom, top, or center for a vertical slider. 6. Use the Numeric Range group box to indicate the numbers to be displayed on the slider scale. You can set the first number to be displayed, the upper limit, and the numbers displayed in between for the increment. 7. Use the Place button at group box to set the position of the buttons to left or bottom, or right or top. 8. Select OK. ═══ 11.11. Adding a Notebook ═══ To add a notebook to a window: 1. Select the Book icon from the Objects toolbox. Drag and drop the icon into the window where you want to add the notebook. Notebook Control Window 2. To simulate a real notebook, pages are bound together at one edge. In the Binding group box, select whether you want the notebook to look like a Solid bound book or a Spiral notebook. 3. The back of the notebook control is shaded to give a three-dimensional effect. Use the Paint Back Pages group box to specify which sides of the notebook are to be shaded. 4. Major tabs are located across from the binding. Minor tabs are located on the side, at right angles to the major tabs. Use the Side of Major Tabs group box to select the position of the major tabs. 5. Select the Tab Sizes push button to display the Tab Sizes pop-up window, as shown in Tab Sizes Window. You can set the height and width (in pixels) of tabs. Tab Sizes Window 6. Select the shape of the tabs that divide the notebook up into sections in the Tab Shape group box of the Notebook Control window. 7. Select whether the tab information is left-justified, right-justified, or centered on the tab in the Tab Justification group box. 8. Select whether the status text is left-justified, right-justified, or centered on the notebook page in the Justify Status group box. 9. Select OK. 10. Each page in the notebook is created as a window or dialog box. Create a window and drop it on the notebook. The Page Details pop-up window appears as shown in Page Details Window. Afterthefirstpageisdroppedonthenotebook ,additionalpagesmustbedroppedonthenotebookitselfratherthanonthecurrentpage .Youcaneditthepagesdirectlyusingtheobjectmanager .Usetheleftandrightarrowsatthebottomofthenotebooktomovebetweenpages . Page Details Window 11. Use this window to create the tabs for your notebook and to determine the order in which they are presented. A Major tab appears, by default, on the right side of your notebook. A Minor tab appears, by default, on the bottom of the notebook page. 12. The order of the tabs is determined by the order in which you add them. To reverse the order of two tabs, select the second tab and click on the Move push button. The second tab becomes the first in the order of presentation. Note: This option only works on the tab shown directly above in the list. 13. After completing the page details, select OK to return to the Notebook Control window. 14. Select OK. ═══ 11.12. Adding a Group Box ═══ 1. Select the Group Box icon from the Objects toolbox. Drag and drop the icon into the window. The Groupbox Item Text pop-up window appears. Group Box Item Text Pop-Up Window 2. If you want a label on the group box, type the text in the Text entry field. 3. If you are assigning your own IDs and #defines, type the values in the ID and #define entry fields. 4. Select OK. ═══ 11.13. Adding Static Text ═══ Static text is the means by which the application presents descriptive information (for example, headings and field prompts) to the user. To add static text to a window: 1. Select the Text icon from the Objects toolbox. Drag and drop the icon into the container. The Text Control pop-up window appears. Text Control Pop-Up Window 2. Type the text you want to add to the window in the Type text entry field. 3. Use the Horizontal options group box to specify how the text should be aligned horizontally: o Align left to left-align the text in the text field o Center X to horizontally center the text within the text field o Align right to right-align the text in the text field 4. Use the Vertical Options group box to specify how the text should be aligned vertically: o Align top to position the text at the top of the text field o Center Y to vertically center the text within the text field o Align bottom to position the text at the bottom of the text field 5. Select OK. If allofthetextisnotdisplayedinthefield ,expandthesizeofthedisplayboxusingthepointertodragtheedgesofthebox . ═══ 11.14. Adding a Rectangle ═══ 1. Select the Rectangle icon from the Objects toolbox. Drag and drop the icon into the window. The Rectangle Controls pop-up window appears. Rectangle Controls Pop-Up Window 2. Use the Styles group box to select the type of rectangle you want to add: ┌──────────────────────────────────┬───────────────────────────────────────────┐ │ RECTANGLE TYPE │ DESCRIPTION │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ FOREGROUND FRAME │ Transparent rectangle in the foreground │ │ │ of your window. │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ FOREGROUND RECTANGLE │ Opaque rectangle in the foreground of │ │ │ your window. │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ HALFTONE FRAME │ Transparent rectangle in the foreground │ │ │ with a half-tone border. │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ HALFTONE RECTANGLE │ Opaque rectangle in the foreground with a │ │ │ half-tone border and filling. │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ BACKGROUND FRAME │ Transparent rectangle in the background │ │ │ of your window. │ ├──────────────────────────────────┼───────────────────────────────────────────┤ │ BACKGROUND RECTANGLE │ Opaque rectangle in the background of │ │ │ your window. │ └──────────────────────────────────┴───────────────────────────────────────────┘ Table 6. Rectangle Types 3. Type the ID and a #define value for the rectangle, if required. 4. Select OK. ═══ 11.15. Adding a Line ═══ You can add a line to your window to improve the design. As you add the line, you can select both the orientation and thickness of it. 1. Select the Line icon from the Objects toolbox. Drag and drop the icon into the window. The Line Controls pop-up window appears. Line Control Pop-Up Window 2. Use the Line Orientation group box to select whether you want to add a horizontal, vertical, ascending, or descending line. The default is horizontal. 3. Use the Thickness list box to select the width of the line, by clicking on any number displayed in the box. The default is 1. 4. Select OK. 5. Once you add the line to the window, expand or shorten the line as required. Use your mouse pointer to create the exact length needed for the window by dragging the borders to the desired length. ═══ 11.16. Adding or Replacing Your Own Icons ═══ You can add your own icons to the set of icons provided in Visual PL/I and use them in your applications. You can also replace an existing icon. To add or replace an icon: 1. Select Icons from the Objects toolbox. Drag and drop the icon into the window. The Icons pop-up window appears. Icons Pop-Up Window All the icons currently loaded into Visual PL/I are named in the Currently available list box. 2. To add an icon named in the list box to a window, select the name and then select OK. To add a new icon to the list box, select the Load push button. See Loading Your Own Icons for Use in a Window below. ═══ 11.16.1. Loading Your Own Icons for Use in a Window ═══ 1. Select Icons from the Objects toolbox. 2. Drag and drop the icon into the window you want the icon to appear. The Icons pop-up window appears. 3. Select the Load push button. The Select an Icon to load pop-up window appears, as shown in Select an Icon to Load Window. Select an Icon to Load Window 4. The Open filename entry field initially displays *·ico. This default entry displays, in the File list box, a list of all files in the selected directory with the file type ico. You can type a different set of filename details in the Open filename entry field and display the names of other files in this directory. For example, if you change *·ico to *.*, the names of all the files in the directory are displayed. 5. The Directory list box initially highlights the name of the directory Visual PL/I is currently using. If you want to load the icon from another directory, select the name of the correct directory from the list box. 6. The File list box lists the names of the files present in the chosen directory. 7. To select the icon file you want to load, either type the name of the file directly into the Open filename entry field or select it from the File list box. 8. To load the file, select OK. Visual PL/I then loads the icon file, closes the Select an Icon to load pop-up window, and returns you to the Icon pop-up window. The name of the new icon is then added to the Currently available list. ═══ 11.16.2. Replacing an Icon in the Currently Available List Box ═══ To replace an icon, do the following: 1. Select an icon name from the Currently available list box. 2. Select the Change push button. The Select an Icon to load window appears. 3. Proceed as described in Loading Your Own Icons for Use in a Window to load the new icon. The name of this new icon replaces the name of the icon that you selected in the Currently available list box. The new icon itself replaces the original icon wherever it occurs in your Visual PL/I applications. ═══ 11.16.3. Replacing an Icon in Your Application ═══ To replace an icon in your application, do the following: 1. Follow the procedure as described in Changing a Control. The Select an Icon to load window appears. 2. Select a new icon from the Currently available list box, or follow the procedure in Loading Your Own Icons for Use in a Window or Replacing an Icon in the Currently Available List Box. ═══ 11.17. Adding Bitmaps ═══ You can use bitmaps created by other graphics packages in your Visual PL/I applications. You can also replace an existing bitmap by following the procedure for changing a control (see Changing a Control) and then adding a new bitmap. 1. Select the Bitmap icon from the Objects toolbox. Drag and drop the icon into the window. The Bitmaps pop-up window appears. Bitmaps Pop-Up Window 2. The names of all bitmaps currently loaded into Visual PL/I appear in the Currently available list box. To add one of these bitmaps to a window, select the one you want from the Currently available list box and then select OK. 3. To add a new bitmap to the list of available bitmaps, select the Load push button. The Select a Bitmap to load window appears. Select a Bitmap to load Window 4. The Open filename entry field initially displays *.bmp. All file names with the file type bmp that are present in the highlighted directory are displayed in the File list box. 5. The Directory output field initially highlights the name of the directory Visual PL/I is currently using. If the bitmap to be loaded is in a different directory, select the appropriate directory name from the list box. 6. The File field lists the names of all bitmap files present in the chosen directory. 7. To select the bitmap file you want to load, type the fully-qualified name in the Open filename entry field. 8. To load the file, select OK. Visual PL/I then loads the bitmap, closes this window, and returns you to the Bitmaps pop-up window, as shown in Bitmaps Pop-Up Window. The name of the new bitmap file is added to the Currently available list box. Select the bitmap file and select OK to insert it. ═══ 11.17.1. Replacing a Bitmap in the Currently Available List Box ═══ To replace a bitmap, do the following: 1. Select a bitmap name from the Currently available list box. 2. Select the Change push button. The Select a Bitmap to load window appears. 3. Proceed as described in Adding Bitmaps to load the new bitmap. The name of this new bitmap replaces the name of the bitmap that you selected in the Currently available list box. The new bitmap itself replaces the original icon wherever it occurs in your Visual PL/I applications. ═══ 11.17.2. Replacing a Bitmap in Your Application ═══ To replace a bitmap in your application, do the following: 1. Follow the procedure as described in Adding Bitmaps. The Bitmaps pop-up window appears. 2. Select a new bitmap from the Currently available list box, or follow the procedure in Loading Your Own Icons for Use in a Window or Replacing a Bitmap in the Currently Available List Box. ═══ 11.18. Adding System Icons ═══ A system icon is an icon that belongs to the OS/2 operating system, such as the `DOS box' icon. You can use system icons in your Visual PL/I applications. You can also replace an existing system icon by following the change procedure and then adding a new system icon. To add a system icon to a window: 1. Select Sys Icons from the Objects toolbox. Drag and drop the icon into the window. The System Icons pop-up window appears. System Icons Pop-Up Window All the available system icons are displayed in the Currently available list box. 2. To add any of the icons in the list box to a window, select the item you want from the list box and select OK. ═══ 11.19. Adding System Bitmaps ═══ A system bitmap is a bitmap that is supplied with the OS/2 operating system, such as the `folder' bitmap. You can use system bitmaps in your Visual PL/I applications. You can also replace an existing system bitmap by following the change control procedure and then adding a new system bitmap. To add a system bitmap to a window: 1. Select the Sys Bitmap icon from the Objects toolbox. Drag and drop the icon into the window. The System Bitmaps pop-up window appears. System Bitmaps Pop-Up Window The names of the currently available system bitmaps are displayed in the Currently available list box. 2. To add one of the bitmaps to a window, select the item you want within the list box and select OK. ═══ 11.19.1. Replacing a System Bitmap in the Currently Available List Box ═══ To replace a system bitmap, do the following: 1. Select a bitmap name from the Currently available list box. 2. Select the Change push button. The Select a Bitmap to load window appears. 3. Proceed as described in Adding Bitmaps to load the new bitmap. The name of this new bitmap replaces the name of the bitmap that you selected in the Currently available list box. The new bitmap itself replaces the original icon wherever it occurs in your Visual PL/I applications. ═══ 11.19.2. Replacing a System Bitmap in Your Application ═══ To replace a system bitmap in your application, do the following: 1. Follow the procedure as described in Adding Bitmaps. The Bitmaps pop-up window appears. 2. Select a new bitmap from the Currently available list box, or follow the procedure in Loading Your Own Icons for Use in a Window or Replacing a Bitmap in the Currently Available List Box. ═══ 11.20. Working with Controls ═══ After you have created the controls for a window, you can: o Make changes to the control o Delete the control o Copy the control, either within the same window or to another window o Change the position and size of a control o Set the style of controls o Change the default presentation parameters of a control ═══ 11.20.1. Changing a Control ═══ To change the attributes you have assigned to an existing control: 1. Position the mouse pointer directly on the control in the active window. 2. Click mouse button 2 to display the context menu. The context menu provides a fast way of working with a control. 3. Select Change from the menu to display the pop-up window for that control. 4. Make the required changes to the control. 5. Select OK. ═══ 11.20.2. Deleting a Control within a Window ═══ To delete a control that has been added to the active window: 1. Position the mouse pointer directly on the control in the active window. 2. Click mouse button 2 to display the context menu. 3. Select Delete. ═══ 11.20.3. Copying a Control within a Window ═══ To make a copy of a control within the active window: 1. Select the control that you want to copy. 2. Click the right mouse button to display the controls menu. 3. Select Copy from the menu. This action creates a copy of the control icon superimposed on the original control icon. 4. Select the control again. 5. Hold down mouse button 1 and drag and drop the copy onto the required position. The copy of the control is moved to the new position, while the control that was copied remains in its original position. You can move the copy to another window. Another method of copying a control is to: 1. Select the control to be copied. 2. Hold down the Ctrl key and mouse button 1 simultaneously and drag and drop the copy of the control onto the required new position. ═══ 11.20.4. Changing the Position or Size of a Control ═══ To change the position or size of a control: 1. Select the control within the active window. 2. Click mouse button 2 to display the context menu. 3. Select Position/Size from the menu. The pop-up window, shown in Position/Size Pop-Up Window, appears to allow you to change both the size and position of the control. Position/Size Pop-Up Window X Pos Pixel position of the control as it appears on the X axis. Y Pos Pixel position of the control as it appears on the Y axis. X Size Length in pixels of the control as it appears on the X axis. Y Size Length in pixels of the control as it appears on the Y axis. ═══ 11.20.5. Setting Control Styles ═══ You can specify certain characteristics for a control you have created within Visual PL/I by using the Window Styles pop-up window: 1. Select the control within the active window. 2. Click mouse button 2 on the control to display a pop-up menu. 3. Select Styles from the menu to display the Window Styles pop-up window. For more information about window style definitions, see Presentation Manager Programming Reference. Window Styles Pop-Up You can select an entry from the WS_Styles list to define some of the characteristics of a control. For example, WS_DISABLED disables the control so that it cannot receive user input. You can select from the Item Styles list to define other characteristics of a control. For example, BS_NOBORDER displays a button without any border. For more information on styles, see Presentation Manager Programming Reference. ═══ 11.20.6. Changing the Default Parameters of a Control ═══ You can change the default parameters of any control or object in the Objects toolbox. Double-click mouse button 1 on the control you want to change in the Objects toolbox to display the Default Parameters pop-up window. Default Parameters Window for Check Boxes You can set the following defaults: Title Text that appears with the icon in the Control Manager window. Initial width Width of the control in pixels as it appears when added to the active window. Initial height Height of the control in pixels as it appears when added to the active window. Initial style Style of the control or object as it appears when added to the active window. ═══ 11.20.7. Working with a Group of Controls ═══ After you define controls for a window, you can define the appearance, position and order of these controls. You can mark them as a group and: o Copy the group to another window o Delete the group from a window o Move the group within the window o Define the sequence in which the cursor moves through the group o Size and align the group horizontally or vertically o Separate the group by equal distances o Center the group horizontally or vertically within a window If you do not like the end result, you can undo the operation. See Undoing Changes Made to Control Size and Alignment. ═══ 11.20.7.1. Identifying Controls as a Group ═══ To take an action on controls as a group, you must first identify the controls that comprise the group. Any action taken then operates on all the members of the group. For example, you can use a single layout action to set the same horizontal size for each control in a group of marked controls. To define a control group: 1. Move the mouse pointer to the first control and click mouse button 2 on it. A pop-up menu appears. 2. Select Styles from the menu. A pop-up window appears. 3. From the WS_Styles list box, select WS_GROUP. You do not have to mark the end of the section. It automatically ends when you begin a new section. ═══ 11.20.7.2. Marking Controls for Further Action ═══ To mark a control: 1. Position the mouse pointer on the control you want to work with. 2. Press the Shift key on your keyboard and click mouse button 1 to mark the control. Note: To mark more than one control, move the mouse pointer to each control and click mouse button 1 while continuing to hold down the Shift key. When you are finished, release the Shift key. All controls you selected are marked for further action. An alternative method of marking a control follows: 1. Move the mouse pointer directly on top of the control in the window and click mouse button 2. 2. Select Layout. 3. Select Mark from the pull-down menu. 4. Mark the control. The border around a control changes color to show that the control has been marked. If you mark more than one control, the colors show the order in which they were marked, as follows: o Brown indicates the first control marked. o Purple indicates the second and subsequent controls marked. o Red indicates the last control marked. All actions that are performed with a marked group use the last marked control as the basis for the action. ═══ 11.20.7.3. Ordering a Group of Controls ═══ 1. Click mouse button 2 on any control in the window. 2. Select Layout. 3. Select Order Group. The controls are placed in the order you have chosen. ═══ 11.20.7.4. Setting the Order in Which the Arrow or Tab Key Moves ═══ Arrow and tab keys let you move the cursor within a window or dialog box if you are not using a mouse. Set the Arrow keys to move the cursor within a group of controls. Set the tab keys to move from group to group. To identify the control to which the tab key carries the cursor, select WS_TABSTOP from the WS_Styles list box, and then mark the control. For example, you may want the tab to stop at the first control in each group. As you mark the controls for a dialog box, mark them in the same order that you want the tab key to follow. As you mark the controls for a window, mark them in reverse order. ═══ 11.20.7.4.1. Additional Step for Windows ═══ You must also add the WM_CHAR message to the window: 1. Display the Links window. 2. Select WM_CHAR from the Event list box. 3. Select Tabbing Functions from the Library list box. 4. Select the Do group tabbing code block from the Code blocks available list box. ═══ 11.20.7.5. Copying a Group of Controls ═══ 1. Mark the controls to be copied. 2. Display the context menu and select Layout from the menu. 3. Select Copy Group from the cascaded menu. 4. Select the window to which the controls will be copied. A pop-up window appears. 5. Select Window from the list of options. 6. The selected controls are copied. The copied control is in the same position (on top of) the selected control in its new window. ═══ 11.20.7.6. Deleting a Group of Controls ═══ 1. In the active project window, mark the controls to be deleted, as described in Marking Controls for Further Action. 2. Display the context menu and select Layout from the menu. 3. Select Delete Group from Layout cascaded menu. If youhaveanylinksattachedtothecontrol ,youmustdeletethelinksbeforeyoucandeletethecontrol .SeeDeletingaLink . ═══ 11.20.7.7. Moving a Group of Controls ═══ Moving a group moves all the controls in a group. However, the controls retain their original position in relation to each other. To move controls within a window: 1. Mark the controls to be moved, as described in Marking Controls for Further Action. 2. Display the context menu for the related control. 3. Select Layout from the menu. 4. Select Move Group from the cascaded menu. 5. Use the mouse to move the control or group to the area required within the client area of the project window. ═══ 11.20.7.8. Ordering a Group of Controls ═══ You can choose the path the cursor takes (from one control to another) when the user presses the Tab and Arrow keys: 1. Mark the controls you want to work with, as described in Marking Controls for Further Action. 2. Position the mouse button on any of the controls you just marked. Click mouse button 2 to display the relevant context menu. 3. Select Layout from the menu. A cascaded menu appears. 4. Select Order Group from the cascaded menu. 5. Select the controls in the order that they are to be processed when the program is being run. The order of selection is set according to the order you specify. ═══ 11.20.7.9. Unmarking Controls ═══ You can unmark a marked control by clicking mouse button 1 on the control while holding down the Shift key. To unmark all controls: 1. Display the context menu by clicking mouse button 2 on one of the marked controls. 2. Select Layout from the menu. A cascaded menu appears. 3. Select Unmark All from the cascaded menu. ═══ 11.20.7.10. Sizing a Group of Controls ═══ You can change the size of the controls in a group by enlarging them or reducing them horizontally or vertically. The last marked control in the group determines the size of the marked controls. To size the controls: 1. Mark the controls, saving the reference control until last. 2. Display the context menu for the control. 3. Select Layout from the context menu. A cascaded menu appears. 4. Select Size X from the cascaded menu to size the group horizontally or Select the Size Y option to size the group vertically. For entry fields with margins, the size is the internal size of the entry field without the margin. ═══ 11.20.7.11. Aligning a Group of Controls ═══ The alignment of a group of controls relates to the position of the controls. It ensures that the controls in the group are horizontally or vertically aligned. The last marked control is used as a reference point for the position of all marked controls. To align the controls: 1. Leaving the reference control (the control that determines the position of the others) until last, mark the controls to be aligned. 2. Select Layout from the context menu. A cascaded menu appears. 3. Select Align X option from the cascaded menu to align the group horizontally. 4. Select Right to align the group to the right edge of the last control or Select Left to align the group to the left edge of the last control. Select the Align Y option to align the group vertically on the Y axis. Select Top to align the group to the top edge of the last control or Bottom to align the group to the bottom edge of the last control. ═══ 11.20.7.12. Positioning a Group of Controls ═══ Use this option to position the controls in a group at equal distances horizontally or vertically. The first and last controls remain fixed, the other controls in the group are moved to achieve equal separations. To separate the controls with equal spaces between consecutive controls: 1. Ensure that the first and last controls are in the correct position and mark the controls to be separated, as described in Marking Controls for Further Action. 2. Display the context menu. 3. Select Layout. A cascaded menu appears. 4. Select Separate X from the cascaded menu to separate the group horizontally or Select Separate Y to separate the group vertically. ═══ 11.20.7.13. Centering Controls ═══ Use this option to center a control or group of controls horizontally or vertically in the window. 1. Mark the control or controls to be centered, as described in Marking Controls for Further Action. 2. Display the context menu for the control. 3. Select Layout from the menu. A cascaded menu appears. 4. Select Center X option from the menu to center the group horizontally, or select Center Y to center the group vertically. ═══ 11.20.7.14. Undoing Changes Made to Control Size and Alignment ═══ If you realigned or sized a control and the result is not satisfactory, you can undo the action as follows: 1. Select the appropriate control. 2. Display the context menu. 3. Select Layout from the context menu. 4. Select Undo from the cascaded menu to reverse the operation. TheUndooptionworksonlyonchangesmadetothesizeoralignmentofacontrolorgroup .Ifyoudeleteagroup ,theUndooptioncannotreversethisaction . ═══ 12. Assigning Accelerators (Shortcut Keys) ═══ An accelerator is a function key or a combination of keys that invokes an application-defined action. An accelerator is also referred to as a shortcut key. These keys provide users with a fast way to perform some activity that would normally be selected from a pull-down. Frequently used actions, such as exiting an application from a File pull-down, are excellent candidates for accelerators. Note: Accelerator keys cannot be defined for pop-up windows or context menus. After you assign the key or key combination to an action, the accelerator is normally displayed opposite the action in the menu or pull-down. An example of an assigned accelerator key combination is shown on the Exit menu option in An Example of a Context Menu, where F3 is synonymous with Exit. When you select an accelerator for an action, Visual PL/I puts the information in an accelerator table, where each accelerator key combination is represented by a tabulated line that describes the keys and the process it affects. The accelerator table is stored in a resource file. ═══ 12.1. Assigning an Accelerator ═══ To assign an accelerator to a window, add an entry to the accelerator table for that window. 1. Select the Accelerator Table icon from the Objects toolbox. 2. Drag the icon into the related window. 3. Release mouse button 2 to display the Accelerator Table Manager pop-up window. Accelerator Table Manager Pop-Up Window The Identifiers list contains the #define parameter name for each window, action bar item, control, and any other item contained within the window. The Current selections list contains a list of currently available accelerators in the form of identifiers, listed with their corresponding key combinations. To add an accelerator table entry to a window, complete the following steps: 1. Select an item from the Identifiers list box. 2. Press the key combinations that you wish to associate with the selected item. 3. Select Add. The key combination and the associated identifier are added to the Current selections list box. 4. Select OK to add the identifier and key combination to the accelerator table for the window. ═══ 12.2. Deleting an Accelerator ═══ To delete an accelerator: 1. Select the accelerator table icon from the Objects toolbox. 2. Drag the icon over to the related window. The Accelerator table manager pop-up window appears. 3. Select the entry from the Current selections list box. 4. Select Delete to remove the entry from the Current selections list. 5. Select OK to delete the entry from the accelerator table and close the Accelerator Table Manager window. ═══ 12.3. Tips on Using Accelerator Keys ═══ Following are some tips on using accelerator keys. ═══ 12.3.1. Multiple keystrokes ═══ Before attempting to type a key combination in the Accelerator Table Manager window, ensure that the Add push button has the focus. If Add does not have the focus, key combinations requiring more than one keystroke, such as Alt+F, do not appear in the key combination box as Alt+F. Alt appears and F overwrites the Alt. ═══ 12.3.2. Alt+C ═══ Using the keystroke combination Alt+C is not recommended. Accelerator keys are active for the system menu of the Accelerator Table Manager window. Selecting Alt+C as an accelerator keystroke combination causes the Accelerator Table Manager to close. ═══ 12.3.3. Case sensitivity ═══ The accelerator keys are case sensitive. Alt+F is not the same as Alt+f. ═══ 12.3.4. Displaying the accelerator key ═══ You can edit the menu to display the accelerator key combination, opposite of the menu text. ═══ 12.3.5. Ensuring the correct ID ═══ If you have forgotten the ID, open the menu icon. Select the item from the list box. The ID appears in the #define field in the #define values group box. ═══ 13. Creating Online Help ═══ Presentation Manager applications can display online help using the Information Presentation Facility (IPF). IPF follows CUA guidelines so that the help interface has a consistent format. Tocreatehelp ,youmustwritethetextusingtheIPFmarkuplanguage .SeeIPFGuideandReference . With Visual PL/I, you can write the help text for a particular window, menu or control. Visual PL/I automatically provides the appropriate online help when the application code is generated, compiled, and run. Visual PL/I assigns a resource identification number to each help panel and writes the code to present it when and where it is required. The user would press PF1 to display the help panels you created. This chapter explains how to add, edit, and delete online help for windows, menus, pull-downs, and controls. To generate code for the help facility, you must link the help panels to your application. See Adding Links for Help. ═══ 13.1. Adding Online Help ═══ To add online help to a window, menu, pull-down or control within Visual PL/I: 1. Position the mouse pointer on the Help icon in the Objects toolbox. 2. Activate the window where you want to add the help panel. 3. Hold down mouse button 2 and drag the icon into the window where the help panel is to be added. 4. Release mouse button 2 to display the Help Information pop-up window. Help Information Pop-Up Window 5. Use the Identifiers list box to select the window, menu item, or control associated with the help. 6. Type the title for the help window in the Help title entry field. 7. Type the help text in the Help text MLE (multi-line entry) field. ThefinalappearanceandlayoutofthetextiscontrolledbyIPFinOS / 2 .Foranycomplextextstructure ,typeyourtextusingIPFtags .Otherwise ,thetextappearsasoneparagraph .SeeInformationPresentationFacilityGuideandReference . 8. Select OK. The help text is activated when you press PF1. ═══ 13.2. Editing Online Help for a Window or Control ═══ To edit existing online help for a window or control created using Visual PL/I: 1. Activate the window where you want to edit the help panel. 2. Select the Help icon from the Objects toolbox. 3. Hold down mouse button 2 and drag the icon into the activated window. 4. Release mouse button 2 to display the Help Information window. 5. Use the Identifiers list box to select the window, menu item, or control associated with the help. 6. Change the help title text or the help text as required. 7. Select OK. ═══ 13.3. Deleting Online Help from a Window or Control ═══ To delete online help that has been added to a window or control: 1. Activate the window where you want to delete the help panel. 2. Select the Help icon from the Objects toolbox. 3. Hold down mouse button 2 and drag the icon into the activated window. 4. Release mouse button 2 to display the Help Information window. 5. Use the Identifiers list box to select the window, menu item, or control associated with the help. 6. To delete the help entry displayed, select Delete. ═══ 13.4. Activating Help from a Push Button ═══ To activate Help from a push button instead of F1: 1. Click mouse button 2 on top of the push button. 2. Select Styles... from the context menu. 3. Select BS_HELP from the ITEM STYLES list box. 4. Select OK. ═══ 13.5. Adding Links for Help ═══ To generate the actual code required to present help for the working application, write the help panels, link them to your application, and then compile and write them. ═══ 13.5.1. Compiling Help for Your Application ═══ Beforeattemptingtocompileanapplicationcontaininghelppanels ,ensurethatyourenvironmentsettingincludestheIPFCdirectoryoftheOS / 2Developer ' sToolkit . For example: SET IPFC = C:\TOOLKT21\IPFC; To check your help panels before compiling the entire application: 1. Move the mouse pointer into any open area of the project window, and click mouse button 2 to display the project context menu. 2. Select the Open arrow. 3. Select Settings from the context menu. The Settings notebook appears. 4. Select the Output Options tab in the notebook. 5. On the notebook page, select only the IPF file (.IPF) as the only output file. 6. Move the mouse pointer to the system icon in the upper left of the notebook, display the system menu, and select Close to close the notebook. 7. Return to the project window, and display the context menu for the project again. 8. Select Build from the menu. Your IPF help panels are written and compiled. 9. IPF compile errors are stored in the error file (.err). To view these errors, display the project context menu and select Source. 10. Select View .err from the cascaded menu. ═══ 13.5.2. Creating Hypertext Links Within Help Panels ═══ To provide hypertext links, leave the Identifiers field blank when you write the help panel. Next, write the code. Then view the IPF file to get the resource numbers (identifiers) that have been assigned. Insert them in the help panels and write the code again. ═══ 14. Creating a Working Prototype ═══ After you have created all of the windows, menus, and controls for your application prototype, you must link them with the action that is to be taken. The process of linking windows, menus, and controls enables Visual PL/I to provide the code blocks that actually create a working prototype. For example, if a user selects a control, an event occurs and a message is sent to Visual PL/I. The receipt of this message results in a specific action being taken. You must provide the links between the event and the resulting action. This chapter takes you through each of the steps required to create and change these links. ═══ 14.1. Adding a Link ═══ To add a link to a menu, window or control: 1. Select the Link icon from the Objects toolbox. 2. Drag and drop the icon onto the related window, menu or control. The Links for... pop-up window appears. Links for... Pop-Up Window 3. The Event list box contains a list of messages that can be received by the control or window. Select the message in the list that represents the event to which the action is to be linked. Double-click mouse button 1 on any item in the Event list box to see an explanation of the selected message. 4. Select the module in which the code block resides from the Library list box. If you are creating a prototype, you usually select Basic PM Functions from the Library list box. 5. Select the code block function from the Code blocks available box. Double-click mouse button 1 on any item in the Code blocks available list box for an explanation of the code block, or see Visual PL/I Code Blocks. 6. Select Add in the Code blocks group box. You may be asked for more information depending on the Visual PL/I variables contained in the code block. You can continue to select and add code blocks. The order in which you select the code blocks determines the order in which the resulting actions are performed. 7. When you have finished adding all the links, select OK. ═══ 14.2. Changing an Existing Link ═══ If, after testing your application, you find that a link is not set up correctly, you can change it. The same window you use to add a link is used to change the link. Over type the previous instructions and change them as required. To change a link to an action bar, window, or control: 1. Select the Link icon from the Objects toolbox. 2. Drag and drop the icon onto the window or the control in the window that requires the change. 3. The Links for... pop-up window appears. 4. Select the code block from the Event links list box. 5. Select Change in the Code blocks group box. If youwanttochangethecodeblocktype ,butnotthedetails ,selectthecodeblockandthenselectDelete .Additsreplacement . For more information, see Working with Links and Code Blocks. ═══ 15. Creating a Working Application ═══ This part provides guidelines for programmers using Visual PL/I to produce working applications. It explains in detail how to create links and use Visual PL/I code blocks in your applications. To design the various items that determine the appearance of an interface, see Designing Your User Interface. ═══ 16. Working with Links and Code Blocks ═══ This chapter explains how to create links between the windows, menus, and controls that comprise your application and create the code blocks necessary to have a working application. See Creating a Working Prototype on how to add links in order to create a working prototype. That chapter is intended for those who want to link windows, menus, and controls of their application design. ═══ 16.1. Code Blocks-An Overview ═══ Code blocks are pre-written lines of code that, when implemented with Visual PL/I, perform certain tasks. A code block can consist of either a simple function call or a set of lines of PL/I source code. When you use Visual PL/I to generate code, the appropriate code blocks are added to your program. See Generating Code for details. Visual PL/I allows you to select the tasks to be performed by your application and associate the appropriate code with the interface components. Visual PL/I provides the code for a wide range of tasks. You can also use your own code and import it into any application you create with Visual PL/I. Code blocks are stored in external files and are loaded either when Visual PL/I is initialized or while you are running Visual PL/I. ═══ 16.2. Using Code Blocks ═══ Visual PL/I provides code blocks that are stored in external files called program library (.PL) files. The Visual PL/I program library files are loaded when Visual PL/I is initialized. You can load .PL files while you are running Visual PL/I to use code blocks you have created. Each code block is either a complete function or some lines of PL/I code placed in other functions. To achieve flexibility, you can insert a set of Visual PL/I variables into the code blocks (for example, WINDOW TITLE). You can resolve these variables implicitly through Visual PL/I, or you can type the values when you add the code block. You can insert links in the following locations: o WM_ messages for any window or dialog procedure. o WM_CONTROL (LN_, BN_, EN_, SPIN_-, and so on) for controls o WM_COMMAND for menu items and push buttons. o Code produced for main link and associated initialization code. ═══ 16.3. Adding Links Between Windows, Menus, and Controls ═══ To add a link to a menu, window, or control: 1. Select the Links icon from the Objects toolbox. Or, you can click on mouse button 2 on the control you want to link. A context menu appears. Select Links. 2. Drag and drop the icon onto the window or the control to which you want to add the link. 3. Click mouse button 2 to display the relevant context menu. 4. Select the Links option. The Links for... pop-up window appears. Links for... Pop-Up Window 5. Select the message from the Event list box that represents the event to which the action is to be linked. 6. Select the module in which the code block resides from the Library box. See Visual PL/I Code Blocks for a complete list of code blocks. 7. Select the code block function from the Code blocks available box. 8. Select Add to add the link. Visual PL/I may prompt you for more information, depending on the variables that are contained in the code block. 9. When you have finished adding all the links, select OK. ═══ 16.4. Deleting a Link ═══ To delete a link that has been added to a window or control: 1. Move the mouse pointer to the Links icon in the Objects tool box. 2. Hold down mouse button 2 and drag the icon into the window or control in the window from which you want to delete the Link. Release mouse button 2. The Links pop-up window appears. 3. Select the message from the Event list. The Event links list box displays any Links attached within the list in the lower left of the Links pop-up window. 4. Select an entry from the list. 5. Select Delete in the Code blocks group box. This action removes the selected link from the list. 6. Select OK. ═══ 16.5. Adding Links for Help ═══ To generate code for the help facility, you must link the help panels to your application. To link the help: 1. Move the mouse pointer to the Links icon in the Objects tool box. 2. Holding down mouse button 2, drag and drop the icon into the client area of the project window. Release the mouse button. The Links pop-up window appears. 3. Select SET_WINDOW_POS from the Event list box. 4. Select Help Manager Function from the Library list box. 5. Select Initialize IPF/2 from the Code blocks available list box. 6. Select Add. 7. When Visual PL/I displays a list of the windows in this project, select the primary window. 8. Select OK. See Compiling Help for Your Application on how to compile help for your application. See Creating Hypertext Links Within Help Panels on how to add hypertext links to your help panels. ═══ 16.6. Adding Main Links ═══ Main links are links inserted into the code in locations that are not part of a window or dialog procedure. Each location has a name by which you can reference. The code that is inserted by default in each place is shown in Main Links Code. Main Links Code HASH_INCLUDES %INCLUDE OS2; %INCLUDE tutorial; PROTOTYPES dcl WINDLG entry(HWND,fixed bin(15), ptr, ptr) EXPENTRY returns(MRESULT); GLOBAL_HANDLES dcl hab0 HAB; GLOBAL_VARIABLES dcl WINDOW HANDLE HWND; dcl WINDOW CLHANDLE HWND; MAIN main: procedure options(main); LOCAL_VARIABLES dcl var1 char(30) varz; dcl var2 fixed bin(15) init('45'xn); dcl qmsg0 QMSG; dcl hmq0 HMQ; INITIALIZE hmq = WinInitialize(null() ); CREATE_MSG_QUEUE hmq = WinCreateMsgQueue(hab,0); CREATE_STD_WINDOW WINDOW HANDLE = WinCreateStdWindow(WINDOW PARENT, WS_VISIBLE, addr(WINDOW FCFVAR), WINDOW CLASS, WINDOW TITLE, ptrvalue(0), null(), WINDOW ID, addr(WINDOW CLHANDLE) ); MESSAGE_LOOP do while ( WinGetMsg(hab0, addr(qmsg), null(), 0, 0) И=0); call WinDispatchMsg( hab, addr(qmsg) ); end; DESTROY_WINDOWS call WinDestroyWindow(WINDOW HANDLE); DESTROY_MSG_QUEUE call WinDestroyMsgQueue( hmq ); TERMINATE1 call WinTerminate( hab ); TERMINATE2 END; /* end main procedure */ If you want to change the code produced for any of the above, create code blocks that do what you require and insert them in the appropriate places. To add the main links to code that has been created by Visual PL/I: 1. Select the Links icon from the Objects toolbox. 2. Drag and drop the icon in the related project window. The Links for Project... pop-up window appears. 3. Select the location from the Event list box. 4. Select PL/I Code Library from the Library list box. 5. Select Any code from the Code Block List and select Add code block. The Any Code dialog box appears. 6. Type the code to be associated with the selected event. 7. Select OK. ═══ 16.7. Viewing Help for Events ═══ To obtain a brief explanation of an event or an option that is available from within the Event list box: 1. Select the Links icon from the Objects toolbox. 2. Drag the icon to the window or the control within the window to which you want to add the link. 3. Release the mouse button 2 to display the Links for... pop-up window. 4. Double-click on an entry within the Event list box. An explanation of the selected event appears. This optionisnotavailableintheLinksforaMenuBarwindow . ═══ 16.8. Creating Code Blocks ═══ To create code blocks for your application, do any of the following: o Use an option called Any Code to add a few lines of code or to add code that is used only once. You cannot reuse it. o Use an option called My Code to add your own code to the code blocks created by Visual PL/I. You can reuse or change at any time when you add code blocks with this method. o Read code blocks stored in a separate file, the Read .pl file. The next time you open the Links window, these code blocks are available for use. See Creating Your Own Code Blocks on how to access these code blocks and read them directly into Visual PL/I. The following sections describe how to create a code block using either of the first two methods. ═══ 16.8.1. Adding a Few Lines of Code ═══ To add several lines of code for one use only: 1. Select the Links icon from the Objects toolbox. 2. Drag and drop the icon onto the window or control in the window to which you want to add the link. The Links for... pop-up window appears. 3. Select All Functions or PL/I Code from the Library list box. 4. Select Any Code from the Code blocks available list box. 5. Select the Add push button. A pop-up window appears. Enter the code...Window 6. Type the PL/I code for the code block in the entry field. 7. Select OK to add the code block to the code block list. YoucannotreusethecodeblockidentifiedasAnycode .Manycodeblocksmayappearinthewindow ,identifiedbythesameterm-Anycode .Youcannotreusethem . ═══ 16.8.2. Adding Your Own Code Block ═══ To add your own code block to an application: 1. Select the Links icon from the Objects toolbox. 2. Drag and drop the icon onto the window or control in the window to which you want to add the link. The Links for... pop-up window appears. 3. Select My Code Block from the Library list box. 4. Select Create to display the Create Code Block window. Create a New Code Block Window 5. Type a unique reference name in the Name field. 6. Type the PL/I code for the code block in the Contents field. 7. Select OK to add the code block to the code block list. The next time you display the Links window, your code block is available for use. ═══ 16.9. Viewing Code Blocks ═══ You can browse through a code block either before or after it is added to your project. To view a code block before it is added to a project: 1. Select the Links icon from the Objects toolbox. 2. Drag and drop the icon onto the window or control in the window to which you want to add the link. The Links for... pop-up window appears. 3. Double-click on an entry within the Code block list list box. The selected code block appears. To view a code block after it has been added to a project: 1. Select the link icon from the Objects toolbox. 2. Drag and drop the icon onto the window or control to which the code block is linked. The Links for... pop-up window appears. 3. Double-click on an entry within the Event list box. The associated code block appears. ═══ 16.10. Using Visual PL/I Code Blocks to Integrate DLL and EXE Projects ═══ To call a window or a dialog stored in a DLL project, the developer of the related EXE project must access the .PMG file of the DLL project. Visual PL/I code blocks provided in the DLL functions module (displayed in the Library list box) enable the EXE project developer to access the data and windows/dialogs in the DLL project. You can use these code blocks the same way as the other code blocks in Visual PL/I. As well as providing code blocks for loading dialogs and creating windows, the DLL functions module contains code blocks that enable you to export and import data from a DLL. A variable is declared for export in the DLL project. To declare it, use the DLL export variable code block that is displayed in the Code blocks available list box. For the EXE project to have access to this variable, the EXE project must call the Import Variable from DLL code block. Accessing the DLL Functions Module ═══ 17. Generating Code ═══ Visual PL/I can generate several types of output files in addition to the .PMG file created when you save an application. You can compile and run a program using these files. This chapter explains how to: o Select the files to be created o Import files for use with your application o Test your application before compiling it o Write and compile the related code o View the code o Execute the compiled source code ═══ 17.1. Selecting Output Files ═══ Visual PL/I can automatically generate the following output files: ┌─────────────────┬────────────────────────────────────────────────────────────┐ │ OUTPUT FILE │ DESCRIPTION │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .CPY │ Header file that contains definitions of identifiers used │ │ │ in the program. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .DEF │ Linker definition file that contains details for the type │ │ │ of project. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .DLG │ Dialog file that contains dialog box specifications. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .H │ Header file that contains definitions of identifiers used │ │ │ by the resource compiler. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .IPF │ IPF file that contains online help text for the program. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .MAK │ Make file that contains instructions for compiling the │ │ │ program. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .PLI │ PL/I code file that contains source code for an applica- │ │ │ tion. │ ├─────────────────┼────────────────────────────────────────────────────────────┤ │ .RC │ Resource file that contains specifications for other │ │ │ resources (for example, windows, menus and icons). │ └─────────────────┴────────────────────────────────────────────────────────────┘ Table 7. Generated Output Files To identify which of these files you want Visual PL/I to create: 1. Double-click mouse button 1 on the project icon. 2. Click mouse button 2 in the client area of the project window to display the context menu. 3. Select the Open arrow to display its related cascaded menu. 4. Select Settings from the menu to display the project Settings notebook. 5. Select the Output options tab to display the Output Options page of the notebook. Output Options Notebook Page 6. Select files you want to generate for the project. You can also select where you want to write window definitions. Window definitions are written out to the .DLG file instead of the .PLI file. Ifyourapplicationistobetranslated ,selectWrite. DLG .ThiseasestheprovisionofNLSinyourprojectbecausetranslatorsworkonresourcefilesonly . ═══ 17.2. Importing a ..res or an ..h File ═══ To import a .res file or an .h file that already exists: 1. Open the related project. 2. Display the context menu for the project. 3. Select Import from the menu. A cascaded menu appears. Viewing Source Files 4. Select the type of file you want to import. You can search for the file within different drives or directories and specify the location of the file. 5. Select OK. ═══ 17.3. Testing a Project ═══ To test a project without leaving Visual PL/I: 1. Select the project window. 2. Display the context menu for the project. 3. Select Test mode from the cascaded menu. Visual PL/I is now in test mode. The project appears as it will when it has been compiled. The selection boundaries are not displayed and the controls react to the mouse. 4. Select Test mode again when you are finished to revert to normal operations. ═══ 17.4. Writing and Compiling Code for a Project ═══ If your project uses the Help Manager facility in Visual PL/I and you have IPF help files to compile, ensure that you have created the necessary links. Otherwise, the code cannot successfully compile. To write and compile the source code for a project: 1. Select the project. 2. Display the context menu for the project by clicking mouse button 2. 3. Select Build from the context menu. Visual PL/I now generates and compiles the output files for each of the types you selected. YoucanalsoselecteitherWriteorCompileseparatelyfromtheBuildcascadedmenu . ═══ 17.5. Viewing Code ═══ After generating your code, you can browse through it and examine any of the output files. To view code: 1. Select the project window. 2. Display the project context menu. 3. Select Source from the menu. Visual PL/I lists all files available. Viewing Source Files 4. Select the relevant file from the list. Visual PL/I displays the code. For example, if you select View PL/I, the source code file for your project appears. 5. To cancel the display, press the Escape key. ═══ 17.6. Executing the Compiled Source Code ═══ It is possible to execute the source code in Visual PL/I. Toexecutethecodeforaproject ,theprojectmustalreadyhavebeencompiledandlinkedsuccessfully . To run your project: 1. Select the project. 2. Display the context menu for the project. 3. Select Run code. Visual PL/I loads your project and displays it as an active primary window. You can now run your program from this window. ═══ 18. Setting Up Your Application for Multitasking ═══ The term multitasking refers to a user's ability to perform several tasks at the same time. This chapter explains how to set up your application for multitasking, through the use of threads. The thread is the means by which OS/2 controls multitasking. This chapter also explains how to create a thread. See Tutorial on Linking a Thread to an Action or Function on how to link a thread to an action or function. ═══ 18.1. Overview of Multitasking ═══ Multitasking allows the system to complete a task independently of other activities, without locking up the entire system. To the user, the activity being performed in the background is not obvious. The user can continue to work on other tasks. When do you need multitasking? One of the most obvious uses is when your application contains elements that may tie up processing time and temporarily halt the application. For example, you may want to transfer files from the host or use an application that accesses a database. To create an application that allows a user to perform several actions simultaneously, you need to associate each action with a specific thread. A thread can have its own local variables and can share global variables with other threads. Each thread has the following characteristics: o It is associated with its own message queue, which it uses to communicate with other threads o It is assigned its own stack, an area of storage allocated for the thread, when it is called. The thread then uses this area to store the temporary information it uses to perform its function. ═══ 18.2. Creating a Thread ═══ In order to create a new thread, you must first define it. After you define the thread, you must then associate it, by means of links, to the object or objects used in performing an action. To define a thread: 1. Open the project to which the thread is to belong. 2. Move the mouse pointer into the project window and click mouse button 2 to display the context menu. 3. Select New from the menu. 4. Select Thread from the cascaded menu to display the Thread Details pop-up window. Thread Details Pop-Up Window 5. Type a unique name in the Thread Name field. 6. Type a queue name in the Queue Name field. The queue name is a valid PL/I variable name and is defined in the PL/I program for use by a thread. The program communicates with the thread through this queue. Messages sent to the queue are processed by the thread in the order in which they arrive. 7. Each message posted to a thread must be prefixed by a message ID. This message identifier is specifically defined in a set of message identifiers. Type the prefix of the message identifier for this thread in the Message identifier field. For example, WM_ is used as a message identifier for a number of predefined messages that can be used in the application. The first two characters of a message identifier must be in uppercase. Visual PL/I allows any message prefixed with WM_ (for example, WM_COMMAND) to be sent to the thread. 8. Select OK. The Thread icon appears in the project window. For more information about using threads, see Tutorial on Linking a Thread to an Action or Function. ═══ 19. Using SQL Support ═══ Visual PL/I helps you include SQL statements in your program. All the necessary precompiling and binding is handled by the PL/I compiler. To help you produce an SQL statement, the tables and columns available for query are displayed by the Enter SQL Statement code block. This chapter takes you through the following steps: o Selecting the database on which the query is to be performed o Using the SQL code blocks provided by Visual PL/I o Compiling and linking Visual PL/I SQL projects ═══ 19.1. Selecting a Database ═══ The first step is to select the database on which the SQL query is to be performed. To select the database: 1. Click mouse button 2 in the client area of the Visual PL/I folder. 2. Select Open... from the menu. 3. Select Settings from the cascaded menu. The Settings notebook appears. 4. Select the Database tab in the notebook. A list of available databases appears. 5. Select the database from the list. Database Page of Settings Notebook Ifthedatabaseyouwanttoworkwithdoesnotappear ,youmustcreateitoutsidetheboundariesofVisualPL / I . 6. Move the mouse pointer to the upper left corner of the notebook and click mouse button 1 to display the system menu. 7. Select Close to process your database selection and to close the notebook. ═══ 19.2. Using the SQL Code Blocks Provided by Visual PL/I ═══ The following are some of the SQL code blocks that imbed SQL statements in the Visual PL/I-generated PL/I code: Start Database It is recommended that you issue this code block in a separate thread. First, create a thread, as described in Setting Up Your Application for Multitasking. Use this code block in the thread. Attach the thread when the program is started. Stop Database Use this code block in the TERMINATE_A point of the main function. You can add code blocks here by dropping the Links icon in the project window and following the steps described in Working with Links and Code Blocks. Enter SQL Statement Two list boxes enable you to enter an SQL statement. The first list box contains a list of the tables in the database you selected. Select a table. The second list box then displays a list of columns in that table. When writing an SQL statement in the multi-line entry field below the list boxes, you must specify which table and columns you are accessing. To do so, double-click on any list box entry and the table or column name is automatically added into the entry field at the current cursor position. Use this code block to create either static or dynamic SQL statements. For static SQL statements: o Begin the statement with EXEC SQL. o Build the statement with a combination of typing in SQL keywords (SELECT, FROM, WHERE...) and selecting table and column names from the two list boxes. o End the statement with a semi-colon (;). For dynamic SQL statements: o Each SQL statement is built as a character string that is assigned to a host variable. For example: STATEMENT = 'SELECT NAME, JOB, SALARY FROM STAFF WHERE SALARY > ?'; o EXEC SQL must not appear in the SQL statement. o Build the SQL statement with a combination of typing in SQL keywords (SELECT, FROM, WHERE...) and selecting table and column names from the two list boxes. o Enclose the SQL statement in single quotes. o End the statement with a semi-colon (;). Begin Host Var Statement If host variables are necessary for your SQL statements, you need to declare them. To declare your host variables: 1. Click on mouse button 2 in the Visual PL/I folder. 2. Select Links. 3. Select the global variables from the Event list box. 4. Select Begin Host Var Statement from the Code blocks available list box. 5. Type your host variable declarations in the editor session, which is provided. 6. Select OK to add your host variable declarations to your program. ═══ 19.3. Setting PL/I Compiler Options ═══ Use the PL/I *PROCESS PP(SQL Statement code block to set the compiler options from within your SQL program. To set the options: 1. Open the project that will use the SQL statements. 2. Click mouse button 2 in the client area of the project window. 3. Select Links... from the menu. 4. Select HASH_DEFINES from the Event list box. 5. Select SQL Functions from the Library list box. 6. Select PL/I *PROCESS PP(SQL Statement from the Code blocks available list box. 7. Select Add. 8. Type the database name when you are prompted. 9. The PL/I *PROCESS PP(SQL Statement code block must precede the #defines line in the Event Links list box. If the #defines line appears ahead of the PL/I *PROCESS PP(SQL Statement code block, do the following: a. Select the #defines line in the Event Links list box. b. Select Move. c. The PL/I *PROCESS PP(SQL Statement appears ahead of the #defines line in the Event Links list box. Links for... Pop-Up Window 10. Select OK to process your database selection and to close the Links for... window. ═══ 19.4. Other Necessary Settings ═══ Make the following update in the Settings notebook of the SQL project. Type this information on the Compile and Link Options page of the Settings notebook for the project, as described in Setting Compile and Link Options. o Add SQL_DYN to the Libraries entry field. The SQL_DYN library contains the routines necessary to support SQL calls from your program. Compile and Link Page of Settings Notebook Make the following change in your CONFIG.SYS file: o Include SQLLIB in the INCLUDE and LIB paths. You must include the database manager directory, SQLLIB, in these paths so that the SQL references are resolved. ═══ 20. Tutorials ═══ This part offers a series of tutorials designed to familiarize you with Visual PL/I. Complete the first tutorial before you go on to the next. ═══ 21. Tutorial on Designing an Application ═══ This tutorial shows you how to: o Create an entry field and delete its contents when a push button is selected. o Create a text entry field. o Create primary and dialog windows. o Create and use menu bars. o Create your own code blocks in an application. o Link the code blocks to events in windows and dialogs. Visual PL / Iprovidesa. PMGfilenamedTutorial .Youcanreferencethiscompletedapplicationwhileyoucreateyourown . This chapter will help you create a project named MYPROJ. ═══ 21.1. Creating a Project ═══ The first step is to create a new Visual PL/I project for the application. A Visual PL/I project is used to define the Presentation Manager windows, menus, and controls that you use for a particular purpose. To create a new project: 1. Start Visual PL/I. 2. Position the mouse pointer in any empty area in the Visual PL/I folder and click mouse button 2 to display the context menu. Project Context Menu 3. Select New... from the menu. The New Project pop-up window appears. New Project Pop-Up Window 4. Type the name of the new project in the entry field. In this tutorial, name the project MYPROJ. 5. Select the New push button to create a project named MYPROJ. An icon representing the project appears in the Visual PL/I folder. A Typical Folder Containing the MYPROJ Icon ═══ 21.2. Creating a New Window ═══ 1. Position the mouse pointer in the Project MYPROJ.PMG window and click mouse button 2 to display the context menu. 2. Select New from the context menu. 3. Select Window from the New cascade. The New Window pop-up appears. Example of New Window Pop-Up 4. Type Firstwin in the Reference name entry field. 5. Type MYPROJ Program in the Title bar text entry field. 6. Select Title bar, System menu, Minimize button and Maximize button in the Window styles group box. The Primary window radio button in the Window Type group box is already selected by default. 7. For the #define entry field, you can type your variable name. Otherwise, Visual PL/I generates a name for you. 8. Select OK to save the window with the specified options. The window is now represented by an icon in the Project MYPROJ.pmg window. Example of New Window Icon ═══ 21.3. Creating a Menu ═══ To create a new menu in the Project MYPROJ.pmg window: 1. Move the mouse pointer into the client area of the MYPROJ project window and click mouse button 2 to display the context menu. 2. Select New from the menu. 3. Select Menu from the Newcascade. This displays a window titled Menu in MYPROJ.pmg. 4. Type FirstMN in the Reference field. 5. Do not select OK at this time. Instead, continue to the next step in this tutorial. ═══ 21.3.1. Creating a Pull-Down Menu for a Menu Item ═══ 1. Type File in the Menu Text field. 2. Type ID_FILE in the #define field. 3. Select Add. New Menu Pop-Up The ID field is given a value automatically and a File menu item appears in the list. ═══ 21.3.2. Adding Items to the New Menu ═══ Next, you are going to create a pull-down menu for this menu item that contains two entries: 1. Select Level 2 on the Indentation Level slider. Place the mouse pointer in the slider, hold down mouse button 1 and drag the slider to the right. Release the mouse button at Level 2. 2. Type Open in the Menu Text entry field, replacing the previous contents. 3. Type ID_OPEN in the #define entry field, replacing the previous contents. 4. Select Add. The Open pull-down item appears in the list box. Open Option Added to Menu 5. Type Exit in the Menu Text entry field, replacing the previous contents. 6. Type ID_EXIT in the #define entry field, replacing the previous contents. 7. Select Add. The Exit pull-down item appears in the list. Exit Option Added to Menu 8. Select OK to save the menu. The menu you have defined is represented by an icon in the Project MYPROJ.pmg window. Menu Icon in Project Window ═══ 21.4. Adding a Menu to a Window ═══ 1. Double-click mouse button 1 on the Firstwin icon in the Project MYPROJ.pmg window to open the window. The MYPROJ Program window and the Objects toolbox are displayed. The Objects toolbox shows the controls that you can add to a window. 2. Select the FirstMN menu icon in the Project MYPROJ.pmg window. 3. While holding down mouse button 2, drag the icon over to the MYPROJ Program window and drop it in the client area. File Menu Added to MYPROJ Project Window The File menu item is added to the window and appears below the title bar. ═══ 21.5. Creating a Dialog Box ═══ 1. Move the mouse pointer into the client area of the project window. 2. Click mouse button 2 to display the context menu. 3. Select New from the context menu. 4. Select Window from the New cascade. The New Window pop-up appears. New Window Pop-Up 5. Type Action in the Reference name entry field. 6. Type Add Files to a List in the Title bar text entry field. 7. Select the Dialog box radio button in the Window Type group box. 8. Select Title bar, System menu, Minimize button, and Maximize button from the Window styles group box. 9. Select dialog border in Border styles group box. 10. Select OK to save the dialog box. It is now represented by an icon in the project window. Dialog Box Icon Displayed in Project Window ═══ 21.6. Adding a List Box ═══ 1. Double-click on the Action icon in the project window. The Add Files to a List dialog box that you just created appears. 2. Select the Listbox icon in the Objects toolbox. 3. While holding down mouse button 2, drag the icon over to the Add Files to a List pop-up window dialog box and drop it. Completing the #Define Field for Your Listbox 4. The #define field of the Listbox #define window contains LI_. Change this to LI_List. 5. Select OK. The Add Files to a List window now contains a list box icon. 6. Position the mouse pointer over the list box. The shape of the pointer changes to a four-headed arrow. 7. Drag the list box to the new position. Resize the list box to a reasonable size: 1. Place the mouse pointer just inside a border of the list box. The pointer changes to a double-ended arrow. 2. Drag the border to a new position. List Box Icon ═══ 21.6.1. Adding Push Buttons ═══ To add an OK push button: 1. Select the Buttons icon in the Objects toolbox. 2. Drag and drop the icon into the pop-up window. This opens the Button Controls window. Button Window 3. Select the type of button you want to create. 4. Type OK in the Button text entry field. 5. Select the #define entry field and overtype PB_ with PB_OK. Push Button Added to Window 6. Select OK. The window should now look like Push Button Added to Window. To add a Fill push button: 1. Select the Buttons icon in the Objects tool box. 2. Drag the icon over to the Add Files to a List pop-up window and drop it onto it. The Buttons Control window appears again. Button Controls Window 3. Type Fill in the Buttons text entry field. 4. Overtype PB_ with PB_Fill in the #define entry field. 5. Select OK. Adding the Fill Push Button You should now have a dialog box containing a list box and two push buttons as shown in Adding the Fill Push Button. You can move or size the push buttons. ═══ 21.7. Creating Links ═══ In this next step, you specify that: o The Open item from the File pull-down in the primary window calls the Add Files to a List pop-up window. o The Exit item ends the application. To do so, establish links between the objects and the functions they represent. ═══ 21.7.1. Creating Links for the Menu Bar ═══ To specify the link for the Open action: 1. Select the Links icon in the Objects toolbox. 2. Drag the icon into MYPROJ Program window and drop it on the icon for FirstMN. The Links for Menu FirstMN pop-up window appears. Links for ... Pop-Up Window IftheLinksforMenuwindowdoesnotappear ,youdidnotpositiontheLinkiconpreciselyoverthemenubeforedroppingit .SelectCancelandtryagain . 3. Select Open in the Event list box. 4. Select Basic PM Functions in the Library list box. 5. Select Load a Dialog in the Code Blocks Available list box. 6. Select the Add push button in the Code block group box. The Single select from list pop-up window now lists the dialog boxes available for selection. 7. Select Action in the list box in this window. 8. Select OK. To specify the link for the Exit actions: 1. Select Exit in the Event list box. 2. Select Basic PM Functions in the Library list box. 3. Select Terminate Application in the Code Blocks Available list box. 4. Select the Add push button in Code block group box. 5. Select OK to save the links for Open and Exit. ═══ 21.7.2. Creating Links for the Dialog Box ═══ Next, you must specify the links that define the action that is to be carried out for the OK and Fill push buttons in the dialog box. When a user of the application selects OK, the dialog box disappears. When the Fill push button is selected, the list box displays the contents of the current directory. 1. Select the Links icon in the Objects toolbox. 2. Drag the icon over to the Add Files to a List pop-up window and drop it on the OK button. The Links for Control OK pop-up window appears. 3. Select WM_COMMAND in the Event list box. 4. Select Basic PM Functions in the Library list box. 5. Select Dismiss the Dialog in the Code Blocks Available list box. 6. Select the Add push button in the Code block group box. The Single select from list pop-up window appears, listing the controls available. 7. Select PB_OK from this list. 8. Select the OK push button in the Single select from list pop-up window to process your entries and close the window. The Links for Control window appears again. 9. Select OK to close the window. Next, specify the link for the Fill push button. 1. Select the Links icon in the Objects toolbox. 2. Drag the icon to the Add Files to a List pop-up window and drop it on the Fill push button. The Links for Control Fill pop-up window appears. 3. Select WM_COMMAND in the Event list box. 4. Select Listbox Functions in the Library list box. 5. Select Display Directory in the Code Blocks available list box. 6. Select the Add push button in the Code block group box. The Single select from list pop-up window appears, giving a list of entry field controls available. 7. Select LI_List in this list. 8. Select the OK push button to process your entries and to close this window. The Links for Control Fill dialog box appears again. 9. Select OK to close the window. ═══ 21.8. Adding Static Text ═══ To add static text to your project window: 1. Select the Text icon in the Objects toolbox. 2. Drag the icon over to the Add Files to a List pop-up window and drop it on the top left of the window, above the list box. The Text Control pop-up window appears. Text Control Pop-Up Window 3. Type My Title in the Type text entry field. 4. Select Center X in the Horizontal options group box. 5. Select Center Y in the Vertical options group box. 6. Type STX_MYTITLE in the #define entry field. This is optional. If you leave this blank, Visual PL/I generates one for you. 7. Select OK. 8. My Title now appears in the entry field of the Add Files to a List window. Resize it with mouse button 1 until you see your text. ═══ 21.9. Adding an Entry Field ═══ 1. Select the Entry Field icon in the Objects toolbox. 2. Drag the icon over to the Add Files to a List pop-up window and drop it on the upper right corner of the list box. The Entry Field Options pop-up window appears. Entry Field Options Window 3. Type My Entry in the Default entry field. 4. Type EF_myentryfield in the #define entry field in the #define value list box. 5. Type my_entryfield in the Variable name entry field. Note: The default for the variable type is global. The my_entryfield variable name will be a PL/I global variable. 6. Select OK. 7. Resize the My Entry entry field in the Add Files to a List window. Add Files to a List Window ═══ 21.10. Adding Another Link to the Fill Push Button ═══ 1. Select the Links icon in the Objects toolbox. 2. Drag the icon to the Add Files to a List pop-up window and drop it on the Fill push button. The Links for Control Fill pop-up window appears. 3. Select WM_COMMAND in the Event list box. 4. Select Entryfield Functions in the Library list box. 5. Select Delete Entryfield Text in the Code Blocks available list box. 6. Select the Add push button in the Code block group box. The Single select from list pop-up window appears, showing a list of entry field controls available. 7. Select EF_MYENTRYFIELD in this list. 8. Select OK in the Single select from list pop-up window. The Links for Control Fill dialog box appears. 9. Select OK to close the window. ═══ 21.11. Adding a PL/I Code Block ═══ 1. Select the Links icon in the Objects toolbox. 2. Drag the icon to the Add Files to a List pop-up window and drop it on the Fill push button. The Links for Control Fill pop-up window appears. 3. Select WM_COMMAND in the Event list box. 4. Select PL/I Code in the Library list box. 5. Select Any code in the Code blocks available list box. 6. Select the Add push button in the Code block group box. The Enter the code... window appears. 7. Type the following in the entry field: /* PL/I code block activated by button */ Display ('The LISTBOX is filled and the ENTRY FIELD is empty.'); This activates the Program Information Display window when the program is invoked. Enter the code... Window 8. Select OK. 9. Select OK to close the window. You have now completed the interface design for a simple application. You will learn to save and compile this design later in this tutorial. ═══ 21.12. Saving, Writing, and Viewing Project Code ═══ To save, write and compile, and view your code: 1. Select mouse button 2 in the client area of the Project MYPROJ.PMG window. 2. Save your project by selecting Save from the context menu for the Project MYPROJ.pmg window. 3. Click on mouse button 2 again in the client area. 4. Select Build to write and compile your code. Select Write code from the cascade menu. Select Compile code from the cascade menu. The Generating Code window appears. The Compilation window appears. When the compilation is done, Completed: Compilation appears in the window title. 5. After the code is written, you can view the stored code on your screen. Click on mouse button 2 in the client area. Select Source. Select one of the View options. If youdonothavetheenvironmentsetupcorrectly ,thecompilestepcanfail .IfVisualPL / IcannotfindthePL / Icompiler : 1. Display the context menu for the project. 2. Select the Open arrow. 3. Select Settings from the cascaded menu. The Settings notebook appears. 4. Select the Compile and Link tab in the notebook. 5. Set up the compiler environment options. 6. Select OK. 7. Try to compile the MYPROJ Program application again. ═══ 21.13. Running the Application ═══ You can run the application without leaving Visual PL/I. Select Run code from the context menu. The first window in your program, the MYPROJ Program window, appears. 1. Select File. Select Open. The Add Files to a List dialog box appears. 2. When you select Fill, the list box fills with all the files in the current directory. The entry field is deleted. The Program Information Display window appears. The previously typed PL/I DISPLAY command in step Adding a PL/I Code Block is invoked. 3. Select OK in the Add Files to a List dialog box. The dialog box disappears. 4. Select Exit from the MYPROJ Program window to end the application. ═══ 22. Tutorial on Linking a Thread to an Action or Function ═══ This tutorial takes you through the steps required to link a thread to an action or function. Before you begin this tutorial, you need to complete the first tutorial, Tutorials. This tutorial requires data that you will supply when you create the application. In this example, the primary window contains a list box that is filled whenever the push button is selected. The system is not locked up while the list box is being filled. During this time, the application can perform other actions. 1. Follow the procedure described in Creating a Thread to create a thread with the thread name Thread1, the queue name queue1, and the message identifier WM_. 2. Select OK. An icon representing thread1 is displayed in the project window. 3. Create a primary main window with a push button and a list box on it. If you completed the tutorial in Tutorials, you already have this window. Display the Objects tool box in order to carry out the rest of this process. Youcannotproceedanyfurtherwiththisprocessuntilyouhavedefinedathread . 4. Drag the Links icon from the Objects tool box and drop it onto the project window for the application (not its primary window). The Links for project window appears. See Links for Project Window. Links for Project Window 5. Select REGISTER CLASS in the Event panel. Scroll down the list to find this entry. 6. Select Thread Functions in the Library panel. 7. Select Create a Thread in the Code Blocks Available panel. 8. Select the Add push button in the Code block group box. This displays the Single select from list window. See Single select from list Window. Single select from list Window 9. Select the Thread1 entry in the list box. 10. Select OK to display the Enter the thread stack size window. See Enter thread stack size Window. Enter thread stack size Window 11. Type an integer value for the stack size. For example, type a value of 10000. 12. Select OK to return to the Links for Project window. 13. Select OK to close the Links for Project window. 14. Select and open the thread icon in the Project window. A small window with the title Thread1 appears. Thread1 Window 15. Drag and drop the Links icon from the Objects toolbox onto the Thread1 icon in the project window. You may need to reposition one of these windows to do this. This opens a Links for Thread window similar to Links for Thread Window. Links for Thread Window 16. Select WM_COMMAND from the Event list. 17. Select Listbox Functions from the Library list. 18. Select Display Current Directory (thread) from the Code Blocks Available list. 19. Select Add Code Block. 20. Select OK. 21. Select the application window that contains the list box and push buttons (Add Files to a list pop-up window in the MYPROJ program.) 22. Drag and drop the Links icon from the Objects window onto the Fill push button icon in the application window. The Links for Control... window appears. Links for Control... Window 23. Select WM_COMMAND in the Event list box. 24. If you are using the MYPROJ program: a. Select Display Directory in the Event links list box. b. Select Delete in the Code block group box. 25. Select Thread Functions in the Library list box. 26. Select Init Directory (thread) in the Code Blocks Available panel. 27. Select Add in the Code blocks group box to display the Single select list from window. 28. Select Thread1 from the list. 29. Select OK to open the Message to be posted window. 30. Type WM_COMMAND in this field. 31. Select OK to open the Single select from list window. 32. Select the identifier LI_LIST that appears in the list box. 33. Select OK to return to the Links for Control ... window. 34. Select OK to close this window. 35. You can now generate the code for this application and compile it, as described in Generating Code. ═══ 23. C2PLI Conversion Aid ═══ This part of the book describes the C2PLI conversion aid. ═══ 24. Converting C Header Files to PL/I ═══ The C2PLI conversion aid converts C header files to the corresponding PL/I include files, with the intent of minimizing manual effort by the user. By using C2PLI to map C header files to the equivalent PL/I include files, you can easily incorporate C programs into the PL/I programming environment. C2PLIdoesnotsupportC + + . C2PLI flags and places detected unsupported features into a block comment in the output file. To avoid using an erroneous file, C2PLI includes a %note in the file. You need to manually complete the conversion and validate the results. Note: It is recommended that you read the CREAD.ME file before you use C2PLI. ═══ 24.1. Before You Start Using C2PLI ═══ Consider the following: o C2PLI is not a parser and has only the scope of a single statement. o C2PLI handles a large subset of declares and defines that are found in header files, but not executable code. Executable code is generally not found in header files. o C2PLI assumes that the C source is valid and compiles cleanly. o C++ class definitions, C++ function prototypes, and C statements that are not valid will produce unpredictable results. Before you use C2PLI, get a clean C compile. ═══ 24.2. Unsupported Features ═══ C features that are not supported: o #define macros o Pragma directives o Functions returning pointer to a function o Typedefs functions o Executable statements o Initialization expressions o Types float and double o Bit fields in struct and unions. Due to differences in storage mapping of bits between C bit fields and the PL/I bit type, this mapping requires manual intervention. o #elif o Enum list within an aggregate Undetected unsupported features may be mapped incorrectly. In severe situations, C2PLI stops processing. ═══ 24.3. Syntax ═══ Syntax C2PLI [drive][path]name.h[[drive][path]outfile.ext] name is the name of a C header file. For example, C2PLI os2def.h By default, the output file that C2PLI creates has the same name, but the extension is cpy. C2PLI creates it in the same subdirectory as the input file. For example, C2PLI os2def.h produces os2def.cpy. If a .cpy file already exists, it is copied to name.bak before the conversion process starts. Any existing .bak file is overlaid. If outfile.ext is specified, the PL/I output is written to that file. If outfile.ext already exists, it is renamed to outfile.bak. If the input file does not have an .h as the extension, C2PLI issues an error message and ends the process. ═══ 24.4. How C2PLI Handles C and PL/I Language Features ═══ This section discusses the following C and PL/I features and how they are handled by C2PLI: o Data types o Names o Continuation and comments o Case sensitivity and restrictions ═══ 24.4.1. Data Types ═══ The C data types supported and the corresponding PL/I equivalents are shown in Data Types. Note that float and double are not included because they are generally not in header files. Integer constants with suffixes L, UL, S, US, and U are supported. ┌───────────────────────┬──────────────────────────────────────────────────────┐ │ C DATA TYPE │ PL/I EQUIVALENT │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "char" │ "char" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "signed char" │ "signed fixed bin(7)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "unsigned char" │ "char" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "char[ ]" │ "char() varyingz" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "int" │ "fixed bin(31)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "short" │ "fixed bin(15)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "long" │ "fixed bin(31)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "unsigned int" │ "unsigned fixed bin(31)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "unsigned short" │ "unsigned fixed bin(16)" │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "unsigned long" │ "unsigned fixed bin(31)" │ └───────────────────────┴──────────────────────────────────────────────────────┘ Table 8. Data Types ═══ 24.4.1.1. Using Value Range to Determine Data Type ═══ Determining Data Type from Value Range shows how C2PLI determines type by looking at the value range. ┌───────────────────────┬──────────────────────────────────────────────────────┐ │ DATA TYPE │ RANGE OF VALUES │ ├───────────────────────┴──────────────────────────────────────────────────────┤ │ UNSIGNED │ ├───────────────────────┬──────────────────────────────────────────────────────┤ │ "char" │ 0 through 255 │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "short" │ 0 through 65535 │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "int, long" │ 0 through 4294967295 │ ├───────────────────────┴──────────────────────────────────────────────────────┤ │ SIGNED │ ├───────────────────────┬──────────────────────────────────────────────────────┤ │ "char" │ -128 through 127 │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "short" │ -32768 through +32767 │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "int, long" │ -2147483648 through +2147483647 │ └───────────────────────┴──────────────────────────────────────────────────────┘ Table 9. Determining Data Type from Value Range ┌────────────────────────────────────────┬─────────────────────────────────────┐ │ C HEX CONSTANTS │ PL/I DECLARES │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ Unsuffixed with 4 or fewer digits │ "fixed bin(15)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ Unsuffixed with 5 to 8 digits │ "fixed bin(31)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ With suffix UL │ "unsigned fixed bin(31)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ With suffix L │ "fixed bin(31)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ With suffix US │ "unsigned fixed bin(16)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ With suffix U │ "unsigned fixed bin(31)" │ ├────────────────────────────────────────┼─────────────────────────────────────┤ │ With suffix S │ "fixed bin(15)" │ └────────────────────────────────────────┴─────────────────────────────────────┘ Table 10. Mapping of C Hex Constants to PL/I Declares ═══ 24.4.2. Names ═══ Because identifiers in PL/I cannot have an underscore as the first character, the first leading underscore is replaced with the character #. ═══ 24.4.3. Continuation and Comments ═══ Using the \ character as a line continuation is supported. C comments (of the form /*...*/) are carried into the output PL/I include file unchanged. C++ comments (of the form //...) are converted to PL/I comments. Block comments inside a function prototype are not supported. ═══ 24.4.4. Case Sensitivity and Restrictions ═══ C is case sensitive and PL/I is not case sensitive. If the C input to C2PLI is dependent on name or value differentiation based on case, the resulting PL/I does not accurately reflect the semantics and intent of the C code. C2PLI issues an error only when the problem is evident within a single statement. For example, #define VAR var results in a warning message being issued. ═══ 24.4.4.1. Macros and Typedef Functions ═══ Macros on #defines and typedef functions are not supported. C pre-defined macros, such as _LINE_ and _DATE_ are not recognized. They are processed as user names resulting in #LINE_ and #DATE_. As with other C-specific names, you need to make the appropriate changes. ═══ 24.4.4.2. C Syntax Variations ═══ C2PLI supports only the syntax specified in the following sections for the different constructs. Except in the case of struct, union, or enum, only a single item is permitted in a declaration statement. While struct and union syntax require each member definition to be fully contained on a line, enumeration list of enum may extend to any number of lines. ═══ 24.4.4.3. Aggregates ═══ Definitions of struct and union within struct and union are supported, but an enum list within an aggregate is not supported. Struct, union, and enum without tags are given the dummy#n tag names, where n is the number of occurrences of the aggregate type without the tag. Nested structs and unions without tags are given the outer struct or union tag name, concatenated with a #. The number of #s increase with the number of nested constructs. ═══ 24.5. C and PL/I Syntax ═══ The following sections describe the C constructs supported by C2PLI and the corresponding PL/I statements that are generated: o #include o #ifdef #else #endif o #ifndef #else #endif o #define directive o #undef directive o Variable declarations o typedef o union o struct o enum o Function declarations ═══ 24.5.1. C Directives ═══ The following sections describe preprocessor directives that conditionally determine which portions of the source are to be compiled. PL/I has no facility by which preprocessor variables can be set outside of the program, such as the DEFINE option in C. C2PLI does not compensate for this difference. Therefore, you need to provide additional setup (using include files, for example) to obtain comparable behavior. ═══ 24.5.2. #include ═══ C syntax #include "fname" or #include fname The name of a C header (.h) file. (fname set by a #define is not supported.) PL/I syntax %include fname; fname The name of the resulting PL/I include file. Mapping for #includes C example PL/I example #include "os2def.h" %include os2def; #include This C directive includes an external file in the header file. Notice that this mapping is a many-to-one correspondence: differentiating between system and user include files has no counterpart in PL/I. All #include statements are mapped to %include statements, and associated search-criteria differences are lost. ═══ 24.5.3. #ifdef #else #endif ═══ C syntax #ifdef identifier statements_1 [#else statements_2] #endif identifier A preprocessor identifier. statements_1 A group of statements to be compiled when identifier is defined. statements_2 A group of statements to be compiled when identifier is not defined. PL/I syntax %dcl identifier char ext; %if identifier ^='' %then %do; statements_1 %end; [%else %do; statements_2 %end;] identifier A preprocessor identifier. statements_1 A group of statements to be compiled when identifier is declared. statements_2 A group of statements to be compiled when identifier is not declared. Mapping for #ifdef #else #endif C example PL/I example %dcl IBMC char ext; #ifdef IBMC %if IBMC ^= '' %then #define Max_Out 100 %do; #else Dcl Max_Out Fixed Bin(31) Value(100); #define Max_Out 50 %end; #endif %else %do; Dcl Max_Out Fixed Bin(31) Value( 50); %end; ═══ 24.5.4. #ifndef #else #endif ═══ C syntax #ifndef identifier statements_1 [#else statements_2] #endif identifier A preprocessor identifier. statements_1 A group of statements to be compiled when identifier is not defined. statements_2 A group of statements to be compiled when identifier is defined. PL/I syntax %dcl identifier char ext; %if identifier = '' %then %do; statements_1 %end; [%else %do; statements_2 %end;] identifier A preprocessor identifier. statements_1 A group of statements to be compiled when identifier is not declared. statements_2 A group of statements to be compiled when identifier is declared. Mapping for #ifndef #else #endif C example PL/I example %dcl IBMC char ext; #ifndef IBMC %if IBMC = '' %then #define Max_Out 100 %do; #else Dcl Max_Out Fixed Bin(31) Value(100); #define Max_Out 50 %end; #endif %else %do; Dcl Max_Out Fixed Bin(31) Value ( 50); %end; ═══ 24.5.5. #if #else #endif ═══ C syntax #if expression statements_1 [#else statements_2] #endif expression A preprocessor relational expression: o Operators && and || are permitted o Functions defined and !defined are permitted. o Operands with type casting are not permitted. statements_1 A group of statements to be compiled when expression evaluates to true. statements_2 A group of statements to be compiled when expression evaluates to false. PL/I syntax %dcl operand char ext; (for all operands) %if expression %then %do; statements_1 %end; [%else %do; statements_2 %end;] expression A preprocessor relational expression. o C operators && and || are mapped to & and |. o C function defined is mapped to ^= ''. o C function !defined(operand) is mapped to ^ (operand ^=" ). Operand names are mapped directly. statements_1 A group of statements to be compiled when expression evaluates to true. statements_2 A group of statements to be compiled when expression evaluates to false. Mapping for #if #else #endif C example PL/I example %dcl DEV_VERSION char ext; %dcl PV_VERSION char ext; #if defined(DEV_VERSION) || %if (DEV_VERSION ^= '') | defined(PV_VERSION) (PV_VERSION ^= '') %then %do; %end; #else %else %do; #endif %end; ═══ 24.5.6. #define Directive ═══ C syntax #define identifier [ ( ] def [ ) ] identifier The name of the identifier being defined. def The definition for identifier. Array notation is not supported. def is: o Any supported C intrinsic type (see Data Types) with the exception of char [ ], with 0 or more * o A constant (integer, string, or hex), which may have the form (type_cast) constant where type_cast is one of the supported types or a user-defined type, assuming that the definition is provided. The only pointer supported for typecast is pointer to type void. o An expression using operators <<, >>, +, and - o A user-defined type o System linkage option: 1. _System 2. _Optlink 3. _Far16 _Pascal 4. _Far16 _Cdecl 5. _Far16 _Fastcall 6. _Far16 7. _Pascal PL/I syntax When def is a C type, the mapping is to define alias identifier PL/I_type; define alias @identifier pointer; When def is a constant, the mapping is to declare identifier ptype value(def); When type_cast is PSZ, the mapping is to declare identifier pointer ptrvalue(def); Otherwise the mapping is to %dcl identifier char ext; %identifier= 'map_val'; [ %dcl @identifier char; %@identifier= '@map_val';] identifier The name of the identifier being defined. PL/I_type The PL/I type that corresponds to C type def. ptype The PL/I type that is proper for the value def. Note that when def includes a type cast to a user-defined type, utype, ptype will be type utype. map_val The value appropriate for the case: o def absent: Y The value 'Y' is used to support tests for %if constructs. There is no direct mapping of C's defined function to PL/I. o expression: the C expression with mappings of: << raise2 >> lower2 + + - - o System-linkage options as follows, corresponding to the list shown in the C syntax: 1. options(linkage (system) byvalue nodescriptor) external 2. options(linkage (optlink) byvalue nodescriptor) external 3. options(linkage (pascal16) byvalue nodescriptor) external 4. options(linkage (cdecl16) byvalue nodescriptor) external 5. options(linkage (fastcall) byvalue nodescriptor) external 6. options(linkage (cdecl16) byvalue nodescriptor) external 7. options(linkage (pascal) byvalue nodescriptor) external o Otherwise, user-defined type: the name of the type (for which the optional statements are generated). The #define directive provides string substitution and is mapped to a PL/I named constant, alias, or %dcl. Because this is a one-to-many correspondence, C2PLI uses the form of the #define statement to deduce the intent of the statement for a meaningful mapping to PL/I. C2PLI must also anticipate the outcome of preprocessing of C and PL/I files. (The "extra" statements for user-defined types in PL/I are the results of this anticipation.) This mapping may not achieve the original intent for various #define/#undef usages that are legal in C, but are not usually found in header files. ═══ 24.5.6.1. Examples ═══ The following examples of mapping of #define statements show a C statement or statements followed by the resulting PL/I statement or statements. Mappingfor# defineDirectives C example PL/I example #define USHORT unsigned short; define alias USHORT unsigned fixed bin(16); define alias @USHORT pointer; #define U15 (USHORT) 22 declare U15 type USHORT value(22); #define IBMC %dcl IBMC char ext; %IBMC = 'Y'; #define TRUE 1 declare TRUE fixed bin(31) value(1); #define TWO 2 declare TWO fixed bin(31) value(2); #define char1 'C' declare char1 char value('C'); #define str "abcd" declare str char value("abcd"); #define WINERR_BASE 0X100A dcl WINERR_BASE fixed bin(15) value('100A'xn); #define NULLHANDLE 0X00000000UL dcl NULLHANDLE unsigned fixed bin(31) value('00000000'xn); #define APIENTRY _System %dcl APIENTRY char scan; %APIENTRY = 'options(linkage (system) byvalue nodescriptor) external'; #define CM_ENTRY _Far16 _Pascal %dcl CM_ENTRY char scan; %CM_ENTRY = 'options(linkage (pascal16) byvalue nodescriptor) external'; #define ptr1 (void far *) 0 declare ptr1 pointer value(ptrvalue(0)); #define U32 (unsigned long) 10 declare U32 unsigned fixed bin(31) value(10); #define U34 ((unsigned long) 10) declare U34 unsigned fixed bin(31) value(10); #define exp ((signed long) +a-b) %dcl exp char ext; %exp = '+a-b '; #define exp1 (signed long) +a-b-c %dcl exp1 char ext; %exp1 = '+a-b-c '; #define FAR %dcl FAR char ext; %FAR = 'Y'; #define NEAR %dcl NEAR char ext; %NEAR = 'Y'; #define RECTL PRECTL %dcl RECTL char ext; %RECTL='PRECTL'; %dcl @RECTL char ext; %@RECTL='@PRECTL'; #define WC_FRAME ((PSZ)0Xffff0001) dcl WC_FRAME pointer value(ptrvalue ('ffff0001'xn)); /* Assume the common definition of PSZ as */ /* typedef char *PSZ; */ /* (pointer to a null-terminated string) */ #define MYVAR (MYTYPE) 333333 dcl MYVAR type MYTYPE value(333333); ═══ 24.5.7. #undef Directive ═══ C syntax #undef identifier identifier The name of the preprocessor identifier whose definition has ended. PL/I syntax %deact identifier identifier The name of the preprocessor identifier being deactivated. Mapping for #undef Directive C example PL/I example #undef myname %deact myname; ═══ 24.5.8. Variable Declarations ═══ C syntax [ const ] type name; type The name of one of the following: o Supported intrinsic type (see Data Types) o User-defined type o struct, union, enum or one of their definitions You can include 0 or more for pointers. Pointers can have attribute far or near, and be of type void. name The name of the object to be typed: o Scalar o Array PL/I syntax dcl name datatype; name The name of the object to be typed. datatype The PL/I type to which the C type is mapped, as given in the following sections. A one-dimensional array of characters is translated into a varyingz character string. A multidimensional character array is treated as an array of characters rather than an array of strings. const is mapped to blank. Mapping for Variable Declarations C example PL/I example unsigned long int int1; dcl int1 unsigned fixed bin(31); char array1[2][4]; dcl array1(0:2-1,0:4-1) char; char ch1[2]; dcl ch1 character (2-1) varyingz; signed long aaa1[ ][4][8][9]; dcl aaa1(0:*,0:4-1,0:8-1, signed fixed bin(31); color v1; dcl v1 type color; short s1; dcl s1 fixed bin(15); int *p1[6]; dcl p1 (0:6-1) pointer; char *ch1; dcl ch1 pointer; struct color Vcol; dcl Vcol type color; union hold value; dcl value type hold; enum scale todays; dcl todays ordinal scale; mytype var1; dcl var1 type mytype; ═══ 24.5.9. typedef ═══ C syntax typedef Ctype name; Ctype One of the following: o Supported intrinsic type (see Data Types) o User-defined type o struct, union, enum or one of their definitions You can include 0 or more * for pointers. Pointers can have attribute far or near, and be of type void. name The name of the type being defined. Array notation is not supported. PL/I syntax define alias name type; define alias @name AddrType; name The name of the type being defined. type The name of the PL/I type that is mapped from the C type or, if type is not an intrinsic C type, is the same name that appears in the typedef statement (assumed to be user-defined). AddrType One of the following: o pointer when Ctype is an intrinsic type or pointer o handle name when Ctype is struct, union, enum, struct name, union name, or enum name o type @user_type when Ctype is a user-defined type It is important to note that a C pointer to an object of intrinsic type maps to a PL/I pointer. However, a pointer to a structure must map to a handle. To properly map C pointers, even when types are chained arbitrarily, the address of the variable is used to refer to the appropriate type. Therefore, each single C typedef statement maps to two PL/I define alias statements in order to map correctly pointers to pointers and handles. The first alias defines the type itself; the second alias defines the type used to address the first and is used to map pointers. Mapping for typedefs shows examples of the mapping for C typedefs and PL/I statements. Mapping for typedefs C example PL/I example typedef int num; define alias num fixed bin(31); define alias @num pointer; typedef num another; define alias another type num; define alias @another type @num; typedef num *numptr; define alias numptr type @num; define alias @numptr pointer; typedef unsigned long apiret; define alias apiret unsigned fixed bin (31); define alias @apiret pointer; typedef long int int1; define alias int1 fixed bin(31); define alias @int pointer; typedef signed short s2; define alias s2 signed fixed bin(15); define alias @s2 pointer; typedef char ch; define alias ch char; define alias @ch pointer; typedef unsigned char uchar; define alias uchar char; define alias @uchar pointer; typedef uchar puchar16; define alias puchar16 type uchar; define alias @puchar16 type @uchar; typedef unsigned char *TYPE; define alias TYPE pointer; define alias @TYPE pointer; typedef int **PPOINT; define alias PPOINT pointer; define alias @PPOINT pointer; C example PL/I example typedef struct _color define structure { 1 #color, int i; 2 i fixed bin(31), } color, v1, *v2; define alias @#color handle #color; define alias color type #color; define alias @color type @#color; define alias v1 type #color; define alias @v1 type @#color; define alias v2 handle #color; typedef COLOR *PCOLOR; define alias PCOLOR type @COLOR; define alias @PCOLOR pointer; typedef COLOR VARCOL; define alias VARCOL type COLOR; define alias vcol handle COL; typedef struct COL vcol; define alias vcol type COL; define alias @vcol type @COL; typedef struct COL *Ptr; define alias Ptr handle COL; define alias @Ptr handle COL; ═══ 24.5.10. union ═══ C syntax union tag { type mname; [type mname; . . . ] } [vlist]; union tag vlist; tag The name for the union. type The type of the member. It is one of the following: o Supported intrinsic type o User-defined type o pointer o struct o union o enum o Definition of struct or union You can include 0 or more * for pointers. Pointers can have attribute far or near, and be of type void. mname The name of the member: o Scalar o Array vlist The list of union variables: o Scalar o Array PL/I syntax define structure 1 tag union 2 name type [, 2 name type .,. . .]; declare var type tag; (Is one declare for each name in vlist) tag The name of the structure type. name The name of a minor structure. type The mapped type. var A name in vlist. Mapping for unions C example PL/I example union hold define structure { 1 hold union, int digits; 2 digits fixed bin(31), short *int1; 2 int1 pointer, long ar[3][4]; 2 letter char; 2 ar dim(0:3-1,0:4-1) fixed bin(31); } var1, var2[6], *var3; dcl var1 type hold; dcl var2(0:6-1) type hold; dcl var3 handle hold; union hold var1, var2[6], *var3; dcl var1 type hold; dcl var2(0:6-1) type hold; dcl var3 handle hold; ═══ 24.5.11. struct ═══ C syntax struct stag { type mname; [type mname; . . . ] } [ svars ]; struct stag var_list; stag The name of the structure type (optional for unnested structs). type The type of the member. It is one of the following: o Supported intrinsic type o User-defined type o pointer o struct o union o enum o Definition of struct or union You can include 0 or more * for pointers. Pointers can have attribute far or near, and be of type void. mname The name of the member: scalar or array. svars A list of variables: scalar or array. var_list A list of variables of type stag: scalar or array. PL/I syntax define structure 1 stag, 2 name mtype [, 2 name mtype, . . . ]; declare var type stag; (Is one declare for each name in var_list) stag The structure type name. mtype The mapped PL/I type. name The minor structure name. var A name in var_list. Mapping for structs C example PL/I example struct COLOR define structure { 1 COLOR; int x; 2 x fixed bin(31), char *letter; 2 letter pointer, PSZ win1; 2 win1 type PSZ, int **p1; 2 p1 pointer, struct addr address; 2 address type addr, union hold money; 2 money type hold, type1 type2; 2 type2 type type1; } var1[5], var2, *var3; dcl var1(0:5-1) type COLOR; dcl var2 type COLOR; dcl var3 handle COLOR; struct COLOR *pcolor, varcol; dcl pcolor handle COLOR; dcl varcol type COLOR; ═══ 24.5.12. enum ═══ C syntax enum enum_tag { e_list } [v_list]; enum enum_tag v_list; enum_tag The type name. e_list The list of enumerations of the form identifier[=constant_int_expression ] that can occur on separate lines. v_list A list of variables of type enum_tag. PL/I syntax define ordinal ordn_type (o_list); declare var ordinal ordn_type; (Is one declare for each name in v_list) ordn_type The name of the ordinal type. o_list The ordinal value list of the form member [ value ]. var A name in v_list. Mapping for enums C example PL/I example enum scale { define ordinal scale off, low, medium=3, high ( off, low, medium value(3), high ); } todays; dcl todays ordinal scale; enum money dollars[6]; dcl dollar(0:6-1) ordinal money; ═══ 24.5.13. Function Declarations ═══ C syntax [extern] RetType [LinkOpts] FuncName (ParmType [parm, ParmType parm, ...]); RetType The function return type: o A supported intrinsic type, except char[ ], with 0 or 1 *. See Data Types. o A user-defined type with 0 or 1 . o Void LinkOpts The name of the linkage option. See list on page #define Directive for recognized system options. FuncName The name of the function. ParmType The type of parameter: o A supported intrinsic type, except char[ ], with 0 or more *. See Data Types. o A user-defined type with 0 or more . o struct, union, or enum. parm The name of the parameter: o Scalar o Array PL/I syntax dcl FuncName entry ( ParmType [, ParmType, ...]) returns (byvalue RetType) [LinkOpts] external; FuncName The name of the function. ParmType The type of the parameter. Note that PSZ maps to char * varyingz byaddr since a definition of typedef char *PSZ is assumed. user_type* maps to @user_type. RetType The function return type. It is one of the following: o Intrinsic types map to PL/I types. o User-defined types map to optional type user_type. o Pointers map to ptr byvalue. LinkOpts The appropriate linkage name. See the list on page #define Directive for a mapping of recognized system options. Mapping for Function Declarations C example PL/I example HWND APIENTRY WinCreateStdWindow dcl WinCreateStdWindow entry (HWND hwndParent, (type HWND , ULONG *flstyle, type @ULONG , PULONG pflCreateFlags[4], type PULONG dim(0:4-1), MYTYPE *Class[6], dim(0:6-1) type @MYTYPE, PSZ psztitle, char (*) varyingz byaddr, long styleclient[4][7] fixed bin(31) dim(0:4-1,0:7-1), HMODULE hmod, type HMODULE, int *id[6][3], dim(0:6-1,0:3-1) pointer, PHWND phwndClient, type PHWND, HWND *hwndParent); type @HWND) returns( byvalue optional type HWND) APIENTRY; HPS APIENTRY WinBeginPaint dcl WinBeginPaint entry (HWND hwnd, (type HWND, HPS hps1, type HPS, PRECTL prclPaint); type PRECTL) returns( byvalue optional type HPS) APIENTRY; int _System fun1(int); dcl fun1 entry (fixed bin(31)) returns(fixed bin(31) byvalue) options(linkage(system) byvalue nodescriptor) external; void * ckmalloc dcl ckmalloc entry (fixed bin(31), (int size, pointer,fixed bin(31)) char *caller, returns (ptr byvalue) int line_number); options (byvalue nodescriptor external; extern int gethostbyname_r dcl gethostbyname_r entry (char *name, (pointer, struct hostent *htent); handle hostent) returns(fixed bin(31) byvalue) options(byvalue nodescriptor) external; int *getname_r dcl getname_r entry (char *name, (pointer, struct hostent *htent[6]); dim(0:6-1) handle hostent) returns(ptr byvalue) options(byvalue nodescriptor) external; ═══ 25. Visual PL/I Code Blocks ═══ Code blocks supplied with Visual PL/I provide a range of frequently used functions or tasks. You can create additional code blocks for additional functions or tasks. You can include a user-written code block almost anywhere in the PL/I source code generated by Visual PL/I. Code blocks are stored in external files and are loaded either when Visual PL/I is initialized or while you are running Visual PL/I. The following list summarizes the code blocks provided with Visual PL/I. ═══ 25.1. Basic PM Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Alarm │ Allows you to select a WA_ message to │ │ │ send to WinAlarm. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Center Window on Screen │ Positions a window at the center of │ │ │ the screen. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Color the Client Area │ Colors the client area with the │ │ │ selected color. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Create a Child Window │ Creates a child window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Create a Window │ Creates a secondary window for your │ │ │ project. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Destroy a Control │ Deletes a control. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Destroy a Window │ Deletes a window and all its │ │ │ descendents. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Destroy a Child Window │ Deletes a child window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Default WM_PAINT │ Contains the default code for a │ │ │ WM_PAINT message. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Disable Control │ Sets a control to the disabled state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Dismiss the Dialog │ Dismisses the dialog box. A Control │ │ │ ID is required as a return value. │ │ │ Normally, this is the ID of the │ │ │ control that was selected to dismiss │ │ │ the dialog. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enable Control │ Sets a control to the enabled state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Force Window to Repaint │ Forces a window to repaint. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Hide a Control │ Hides a control on the current │ │ │ window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Load a Dialog │ Loads the dialog box (modal). │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Load a Dialog (modeless) │ Loads the dialog box (modeless). │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Load A Window from a Window Template │ Loads a window from a window tem- │ │ │ plate. The "Output all windows to │ │ │ DLG file" option on the output │ │ │ options dialogs must be checked for │ │ │ this to work. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Resize Window to Full Screen │ Resizes a window to the full screen │ │ │ size. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Resize Parent Window to Full Screen │ Resizes a parent window to the full │ │ │ screen size. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Send WM_ Message │ Sends a WM_ message selected from a │ │ │ list to the current window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Send WM_ Message to a Window │ Sends a WM_ message selected from a │ │ │ list to any window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Focus to Control │ Sets the focus to a control. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Parent │ Sets the parent of a child window to │ │ │ be the desktop window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Parent of Window to Another │ Sets the parent of a child window to │ │ Window │ be another window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Owner │ Sets the owner of a child window to │ │ │ be the desktop window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Owner of Window to Another │ Sets the owner of a child window to │ │ Window │ be another window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Static Text │ Enables you to change a static text │ │ │ control entry. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Window Title │ Sets the title text of a window. │ └──────────────────────────────────────┴───────────────────────────────────────┘ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Terminate Application │ Terminates the application. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ UnHide a Control │ Shows a control on the current │ │ │ window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ WinDefWindowProc │ Contains the default process for a │ │ │ message sent to dialog procedure. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 11. Basic PM Functions ═══ 25.2. Button Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Check a Button │ Sets a check box to the checked │ │ │ state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Uncheck a Button │ Sets a check box to the unchecked │ │ │ state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Click a Button │ Clicks a button. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enable a Button │ Sets the button control to an enabled │ │ │ state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Disable a Button │ Sets the button control to a disabled │ │ │ state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Highlight a Button │ Displays a button control in the │ │ │ highlighted state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Unhighlight a Button │ Displays a button control in the │ │ │ unhighlighted state. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Button Checked │ Determines if the button is checked │ │ │ and executes one or more code blocks │ │ │ if it is. If more than one code │ │ │ block is to be executed, ensure that │ │ │ they are delimited by DO and END │ │ │ statements. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Button Unchecked │ Determines if the button is unchecked │ │ │ and executes one or more code blocks │ │ │ if it is. If more than one code │ │ │ block is to be executed, ensure that │ │ │ they are delimited by DO and END │ │ │ statements. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 12. Button Functions ═══ 25.3. Color Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Control Color (Background) │ Sets the control's background color. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Control Color (Foreground) │ Sets the control's foreground color. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 13. Color Functions ═══ 25.4. DLL Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Create A Child Window from a DLL │ Call and create a child window │ │ │ defined in a PL/I for OS/2 Toolkit │ │ │ DLL project. The parent window will │ │ │ be the window from which the code │ │ │ block is called. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Create A Window from a DLL │ Call and create a window defined in a │ │ │ PL/I for OS/2 Toolkit DLL project. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ DLL Export Variable │ Define a variable for export from a │ │ │ DLL project. This code block creates │ │ │ a variable which may be referenced in │ │ │ a .EXE by the "Import Variable from │ │ │ DLL" code block. Use this function │ │ │ within a DLL project only. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Dynamically Call a DLL Dialog │ The DLL containing the dialog is │ │ │ loaded at the point in time when the │ │ │ dialog is loaded; otherwise, the DLL │ │ │ is loaded when the .EXE is loaded. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Import Variable from DLL │ This code block references a variable │ │ │ declared in a DLL using the "DLL │ │ │ Export Variable" code block. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Load A Dialog from a DLL │ Loads a modal dialog from a PL/I for │ │ │ OS/2 Toolkit DLL project. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Load A Modeless Dialog from a DLL │ Load a modeless dialog from a PL/I │ │ │ for OS/2 Toolkit DLL project. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 14. DLL Functions ═══ 25.5. DOS Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ DosExit │ Exits the program using the "DosExit" │ │ │ call. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Get Pathname of Work Dir │ Returns the pathname of the current │ │ │ directory. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 15. DOS Functions ═══ 25.6. Entry Field Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Delete Entryfield Text │ Allows you to delete the contents of │ │ │ an entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Read Entry Field (32) │ Reads the contents of an entry field │ │ │ that has a maximum size of 32 charac- │ │ │ ters into a variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Read Entry Field │ Reads the contents of an entry field │ │ │ into a variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Entryfield Read-Only │ Allows you to make an entry field │ │ │ read-only. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Entryfield Text │ Allows you to set the entry field │ │ │ text. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 16. Entry Field Functions ═══ 25.7. Font Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Get Available Fonts into Listbox │ Gets the list of available fonts and │ │ │ displays them in a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Font of Control from Variable │ Sets the font of a control from a │ │ │ font variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Font of Entry Field from Vari- │ Sets the font of an entry field from │ │ able │ a font variable. A valid font name │ │ │ begins with a point size, such as │ │ │ 14.Tms Rmn. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Font of Listbox from Variable │ Sets the font of a list box from a │ │ │ font variable. A valid font name │ │ │ begins with a point size, such as │ │ │ 14.Tms Rmn. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 17. Font Functions ═══ 25.8. Help Manager Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Initialize IPF/2 │ Initializes IPF (this code block is │ │ │ required for on-line help). Add this │ │ │ code block after the SET_WINDOW_POS │ │ │ window message within the main links. │ │ │ The main links are found when the │ │ │ links icon is dropped on the project │ │ │ window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Show Help for Help │ Displays help for the selected item. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 18. Help Manager Functions ═══ 25.9. List Box Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Add Entry Field Contents to Listbox │ Adds the contents of an entry field │ │ │ into a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Clear Listbox │ Deletes all the items from a list │ │ │ box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Copy Selected Listbox Item to Entry │ Copies the selected list box item │ │ Field │ into an entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Copy sitemIndex Listbox Item to │ Queries the selected list box item, │ │ szstr │ which is stored in the variable │ │ │ sitemIndex and copies its text into │ │ │ the local variable szstr. The vari- │ │ │ able is automatically declared for │ │ │ you as char(256) varyingz. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Delete All Selected Listbox Items │ Deletes from a list box all the │ │ │ selected items. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Delete Listbox Item(sitemIndex) │ Deletes a list box item, which is │ │ │ referenced by the variable │ │ │ sitemIndex. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Deselect All Listbox Items │ Deselect all items in a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ DeSelect Listbox Item │ Deselects an item in a list box. The │ │ │ first item index is 0. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Display Directory │ Displays the current directory in a │ │ │ list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Display Specific Directory │ Displays the specified directory │ │ │ within a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Do While (sitemIndex к= LIT_NONE); │ Allows you to enter any code if the │ │ ANYCODE │ variable sitemIndex does not refer- │ │ │ ence an item in the list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Dynamic Search of Listbox from Entry │ Dynamically searches a list box for │ │ Field │ the text entered into an entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Dynamic Search of Listbox from Vari- │ Dynamically searches a list box for │ │ able │ the value in the specified variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enable/Disable Button on Listbox │ Changes the selection status of a │ │ Selection │ button control when any list box item │ │ │ is selected. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enter Text into Listbox in Ascending │ Sorts the items in a list box in │ │ Order │ ascending order according to when │ │ │ they were entered. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enter Text into Listbox in │ Sorts the items in a list box in │ │ Descending Order │ descending order according to when │ │ │ they were entered. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If sitemIndex = LIT_NONE then │ Allows you to enter any code if the │ │ ANYCODE │ variable sitemIndex does not refer- │ │ │ ence an item in the list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Read Listbox into Variable when Item │ Read a list box item into a variable │ │ Selected │ when the item is selected. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Replace Selected Listbox Item with │ Replaces a selected list box item │ │ Entry Field Contents │ with the contents of an entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Select All Listbox Items │ Select all the items in a list box. │ │ │ Note that you must select │ │ │ LS_MULTIPLESEL. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Select Listbox Item │ Selects an item in a list box. The │ │ │ first item index is 0. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Listbox Text │ Inserts an item into a list box │ │ │ control at the end of the list. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Listbox Text from Variable │ Add the contents of a variable to the │ │ │ end of the list. │ └──────────────────────────────────────┴───────────────────────────────────────┘ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set sitemIndex to First Selected │ Sets the variable sitemIndex to ref- │ │ Listbox Item │ erence the first selected item within │ │ │ a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set sitemIndex to Next Selected │ Sets the variable sitemIndex to ref- │ │ Listbox Item │ erence the value of the next selected │ │ │ item within a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Sort a Listbox in Ascending Order │ Sorts the contents of a list box in │ │ │ ascending order. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Sort a Listbox in Descending Order │ Sorts the contents of a list box in │ │ │ descending order. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Start Application from Listbox Entry │ Start an application from an entry │ │ │ selected within a list box. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 19. List Box Functions ═══ 25.10. Menu Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Check a Menu │ Adds a check mark next to a menu item │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ UnCheck a Menu │ Removes a check mark from a menu item │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enable a Menu │ Enables a menu item, making it avail- │ │ │ able for selection │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Disable a Menu │ Disables a menu item, making it una- │ │ │ vailable for selection │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Highlight a Menu │ Highlights a menu item │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ UnHighlight a Menu │ Turns off the highlight attribute for │ │ │ a menu item │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 20. Menu Functions ═══ 25.11. Message Box Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ ADD When MBID_*: │ Allows you to take action based on │ │ │ the result of the Message Box. To be │ │ │ used in conjunction with "SELECT ( │ │ │ UsResponse )" and "END SELECT". │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ END SELECT │ Contains the default part of a SELECT │ │ │ statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If ( usResponse = MBID_* ) ANYCODE │ Allows you to specify action to be │ │ │ taken based on the result of the │ │ │ Message Box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Message Box │ Displays a message box and returns │ │ │ the result in the variable │ │ │ usResponse. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Message Box (dialog) │ Displays a message box and returns │ │ │ the result in the variable │ │ │ usResponse. Use this code block │ │ │ within a dialog box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Simple Exclamation/Enter Message Box │ Displays a simple message box with an │ │ │ ENTER button. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SELECT ( usResponse ) │ Allows you to specify action to be │ │ │ taken based on the result of the │ │ │ Message Box. To be used in conjunc- │ │ │ tion with "ADD When MBID_*:" and "END │ │ │ SELECT". │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 21. Message Box Functions ═══ 25.12. Multi-Line Entry Field Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Clear Current Text Selection │ Deletes the selected text within a │ │ │ multi-line entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Clear MLE Text │ Deletes all text from the MLE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Copy Current Selection to Clipboard │ Copies the selected text from a │ │ │ multi-line entry field to the clip- │ │ │ board. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Copy Selection to Clipboard and │ Copies the selected text from a │ │ Delete │ multi-line entry field to the clip- │ │ │ board and deletes it. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Paste Current Selection from Clip- │ Overwrites the selected text with │ │ board │ text from the clipboard. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set MLE Read-Only Mode │ Sets a multi-line entry field to be a │ │ │ read-only field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set MLE Read/Write Mode │ Sets a multi-line entry field to be │ │ │ in read/write mode. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set MLE Text from String │ Inserts text in a multi-line entry │ │ │ field. If text is selected within │ │ │ the entry field, it is replaced by │ │ │ the string; otherwise, the string is │ │ │ inserted in the entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set MLE Text from Variable │ Inserts character data identified by │ │ │ the variable in a multi-line entry │ │ │ field. If text is selected within │ │ │ the entry field, it is replaced by │ │ │ the string; otherwise, the string is │ │ │ inserted in the entry field. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Undo Last MLE Operation │ Undoes the last operation on the │ │ │ multi-line entry field. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 22. Multi-Line Entry Field Functions ═══ 25.13. PL/I Code Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Any Code │ Allows you to write or copy code from │ │ │ another file into your application. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Break Statement │ Adds a BREAK statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Char Variable │ Declares a character string of speci- │ │ │ fied length. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ DO Statement │ Adds a DO statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ END Statement │ Adds an END statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Else Statement │ Adds an ELSE statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Global Char Variable │ Declares a global char varyingz vari- │ │ │ able. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Global fixed bin(16) unsigned │ Declares a global fixed bin(16) │ │ │ unsigned variable and initializes it │ │ │ to zero. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Global fixed bin(31) unsigned │ Declares a global fixed bin(31) │ │ │ unsigned variable and initializes it │ │ │ to zero. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Global Pointer Variable │ Declares a global pointer variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Statement │ Adds an IF statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Local Char Variable │ Declares a local char varyingz vari- │ │ │ able. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Local Fixed Bin(16) Unsigned │ Declares a local fixed bin(16) │ │ │ unsigned variable and initializes it │ │ │ to zero. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Local Fixed Bin(31) Unsigned │ Declares a local fixed bin(31) │ │ │ unsigned variable and initializes it │ │ │ to zero. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Local Pointer Variable │ Declares a local pointer variable. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 23. PL/I Code Functions ═══ 25.14. Pop-Up Menu Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Display Pop-up Menu │ Displays a pop-up menu. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 24. Pop-Up Menu Functions ═══ 25.15. Slider Control Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Shaft Dimensions │ Sets breadth of shaft. Query Shaft │ │ │ Dimensions returns two values. Only │ │ │ the breadth can be adjusted. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Shaft Position │ Sets the x- and y-position of the │ │ │ lower-left corner of the slider shaft │ │ │ in the slider window. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Arm Dimensions │ Sets the width and height of the │ │ │ slider arm. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Arm Position (Pixels) │ Sets the position of the slider in │ │ │ pixels. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Arm Position (Increment) │ Sets the position of the slider as an │ │ │ increment position. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Shaft Dimensions │ Queries for the length and the │ │ │ breadth of the slider shaft. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Shaft Position │ Queries for the x- and y-position of │ │ │ the lower-left corner of the slider │ │ │ shaft. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Arm Dimensions │ Queries for the length and breadth of │ │ │ the slider arm. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Arm Position (Pixels) │ Queries for the position of the │ │ │ slider arm. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Arm Position (Increment) │ Queries for the position of the │ │ │ slider arm. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Add Detent │ Places a detent along the slider │ │ │ shaft at the specified number of │ │ │ pixels from home. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Delete Detent │ Removes a previously specified │ │ │ detent. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Detent Position │ Queries for the current position of a │ │ │ detent. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Scale Text │ Sets text above tick mark. The text │ │ │ is centered on the tick mark. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Scale Text │ Queries for the text associated with │ │ │ a tick mark and copies it into the │ │ │ specified variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Tick Size │ Sets the size of a tick mark. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set All Tick Sizes │ Sets the size of all tick marks. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Tick Size │ Queries for the size of a tick mark. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Tick Pos │ Queries for the position of a tick │ │ │ mark. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 25. Slider Control Functions ═══ 25.16. Sound Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Make Another High Beep Noise │ Sounds a very high beep. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Make a High Beep Noise │ Sounds a high beep. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Make a Low Beep Noise │ Sounds a low beep. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 26. Sound Functions ═══ 25.17. Spin Button Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query Spin Button Text │ Queries the current value displayed │ │ │ on the specified spin button. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Spin Set Array │ Sets the range of numeric values │ │ │ associated with the spin button to be │ │ │ those defined for this control in the │ │ │ spin button controls dialog box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Spin Set Initial Item │ Sets the initial value for the │ │ │ selected spin button. It is midway │ │ │ through the range of numeric values │ │ │ defined for this control in the spin │ │ │ button controls dialog box. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 27. Spin Button Functions ═══ 25.18. SQL Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Any SQL code │ Allows you to write or copy SQL code │ │ │ from another file into your applica- │ │ │ tion. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Begin Host Var │ Declares all SQL host variables in │ │ │ this section. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Enter SQL │ Helps to build an SQL statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Include SQLCA Structure │ Includes the SQLCA structure. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Include SQLDA Structure │ Includes the SQLDA structure. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ PL/I *PROCESS PP(SQL │ Invokes the PL/I SQL preprocessor. │ │ │ Place it ahead of the 'HASH_DEFINES' │ │ │ Main Links section. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Query SQLCA Return Code │ Queries the SQL variable SQLCODE with │ │ │ an IF statement. Requires an END │ │ │ statement after the intervening code. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Commit │ Ends a unit of work and commits the │ │ │ database changes that were made by │ │ │ that unit of work. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Connect to Database │ Connects the application process to │ │ │ the database. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Connect Reset │ Disconnects the application process │ │ │ from the current database. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL DECLARE CURSOR Statement │ Defines a cursor for a prepared │ │ │ statement. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL CLOSE CURSOR │ Closes the named cursor. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Display Error Codes │ Displays the SQL error codes to │ │ │ SYSPRINT (for debugging purposes). │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL_ERROR Block │ Used in conjunction with SQL Whenever │ │ │ statement for SQL error handling. │ │ │ Displays the values of the SQL error │ │ │ variables when an error condition is │ │ │ raised. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL_EXIT │ Used in conjunction with SQL_ERROR │ │ │ block for SQL error handling. Causes │ │ │ the next sequential instruction of │ │ │ the source program to be executed. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL FETCH │ Positions a cursor on the next row of │ │ │ its result table and assigns the │ │ │ values of that row to host variables. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Open Cursor │ Opens a cursor so that it can be used │ │ │ to fetch rows from the result table. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Open Cursor Using Host Variables │ Opens a cursor so that it can be used │ │ │ to fetch rows from the result table. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL PREPARE │ Dynamically prepares an SQL statement │ │ │ for execution. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Rollback Statement │ Ends a unit of work and backs out the │ │ │ database changes that were made by │ │ │ that unit of work. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ SQL Whenever │ Used in conjunction with SQL_ERROR │ │ │ block for SQL error handling. Speci- │ │ │ fies the action to be taken when the │ │ │ SQLERROR error condition is raised. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Start Database │ Starts the database manager through │ │ │ the SQLGSTAR API call. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Stop Database │ Stops the database manager through │ │ │ the SQLGSTDM API call. │ └──────────────────────────────────────┴───────────────────────────────────────┘ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Until SQLRC is not OK │ Performs a loop until SQLCODE returns │ │ │ a 'not found' condition. Requires an │ │ │ END statement after the intervening │ │ │ code. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 28. SQL Functions ═══ 25.19. String Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Concatenate Str2 to Str1 │ Appends the second string to the │ │ │ first string. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Copy Str2 to Str1 │ Copies Str2 to Str1. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Declare String Variable │ Declares a character varyingz string │ │ │ variable type and defines the length │ │ │ of the variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 Equal to Str2 ANYCODE │ Checks if the first string variable │ │ │ is equal to the second. If they are │ │ │ equal, executes ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 Not Equal to Str2 ANYCODE │ Checks if strings are not equal. If │ │ │ they are NOT equal, executes ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 Less than Str2 ANYCODE │ Checks if the first string variable │ │ │ is less than the second. If this │ │ │ condition is fulfilled, executes │ │ │ ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 Greater than Str2 ANYCODE │ Checks if the first string variable │ │ │ is greater than the second. If this │ │ │ condition is fulfilled, executes │ │ │ ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 CaseIns Equal to Str2 │ Checks if the first string variable │ │ ANYCODE │ is equal to the second regardless of │ │ │ case. If this condition is ful- │ │ │ filled, executes ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 CaseIns Not Equal to Str2 │ Checks if the first string variable │ │ ANYCODE │ is NOT equal to the second regardless │ │ │ of case. If this condition is ful- │ │ │ filled, executes ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 CaseIns Less than Str2 │ Checks if the first string variable │ │ ANYCODE │ is less than the second regardless of │ │ │ case. If this condition is ful- │ │ │ filled, executes any code. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ If Str1 CaseIns Greater than Str2 │ Checks if the first string variable │ │ ANYCODE │ is greater than the second regardless │ │ │ of case. If this condition is ful- │ │ │ filled, executes ANYCODE. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Set Str to Uppercase │ Converts any lowercase letters in the │ │ │ string to uppercase. Other charac- │ │ │ ters are not affected. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 29. String Functions ═══ 25.20. Tabbing Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Do Group Tabbing │ When added to a WM_CHAR message, │ │ │ allows the user to tab around the │ │ │ controls within a window. This │ │ │ feature is automatically handled by │ │ │ PM for dialog boxes. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 30. Tabbing Functions ═══ 25.21. Task Manager Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Add Application to Tasklist │ Adds an entry in the task list for │ │ │ this application. If you want your │ │ │ program name (for example, "app.exe") │ │ │ to appear as the title, type NULL. │ │ │ Otherwise, type the application name │ │ │ in quotes or in a variable. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Change Tasklist Entry Title │ Changes an application's entry in the │ │ │ task list. The application must have │ │ │ a task list entry before executing │ │ │ this code block. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Remove Application Entry From │ Removes an application's entry from │ │ Tasklist │ the task list. The application must │ │ │ have a task list entry before exe- │ │ │ cuting this code block. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 31. Task Manager Functions ═══ 25.22. Thread Functions ═══ ┌──────────────────────────────────────┬───────────────────────────────────────┐ │ FUNCTION │ DESCRIPTION │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Create A Thread │ Creates a thread. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Display Directory (thread) │ Performs the Display Directory func- │ │ │ tion within the thread and displays │ │ │ the output (the resulting directo- │ │ │ ries) in a list box. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Init Directory (thread) │ Posts a message to the message queue │ │ │ of a thread. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Kill Thread │ Deletes the specified thread. │ ├──────────────────────────────────────┼───────────────────────────────────────┤ │ Post Text Message to Thread │ Posts the specified message to the │ │ │ thread's message queue. │ └──────────────────────────────────────┴───────────────────────────────────────┘ Table 32. Thread Functions ═══ 26. Creating Your Own Code Blocks ═══ When Visual PL/I generates the code for an application, the links you define between your windows, menus, and controls result in the calls to PM functions being included in the application code. Visual PL/I provides many code blocks for use in your PM application. However, you can also create your own code blocks and import them into Visual PL/I. This chapter explains how to create and use your own code blocks for inclusion in Visual PL/I applications. ═══ 26.1. Where Code Block Information is Stored ═══ Code blocks supplied with Visual PL/I provide a range of frequently used functions or tasks. You can create additional code blocks for additional functions or tasks. You can include a user-written code block almost anywhere in the PL/I source code generated by Visual PL/I. Code blocks are stored in external files and are loaded either when Visual PL/I is initialized or while you are running Visual PL/I. Information about code blocks is held in the following files: ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 33. Code Block Files │ ├───────────────────┬──────────────────────────────────────────────────────────┤ │ FILE │ DESCRIPTION │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PL file │ Consists of a list file identifying the other files │ │ │ (.PLO, .PLM, and .PLF), which contain code blocks and │ │ │ information about them. │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PLC file │ Header files that contain C definitions of identifiers. │ │ │ They are added to the Visual PL/I list of system con- │ │ │ stants. │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PLF file │ Contains the source modules for the code blocks named in │ │ │ the CODE BLOCKS AVAILABLE list box in the LINKS FOR │ │ │ PROJECT... dialog box. To include a code block in the │ │ │ application, select its name from the list box. │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PLM file │ Contains the names that appear in the MODULE LIBRARY │ │ │ list box within the LINKS dialog box and the names asso- │ │ │ ciated module and object files stored in the ·PLF file │ │ │ to be included, if selected. │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PLO file │ Contains a record consisting of the source and object │ │ │ file names and the PL/I compiler options needed to │ │ │ compile each code block in a project. │ ├───────────────────┼──────────────────────────────────────────────────────────┤ │ .PLP file │ Header files that contain PL/I definitions of identi- │ │ │ fiers. They are added to the Visual PL/I list of system │ │ │ constants. │ └───────────────────┴──────────────────────────────────────────────────────────┘ ═══ 26.2. Structure of Code Block Files ═══ The following sections define the structure of the files in which code block information is stored. ═══ 26.2.1. Program Library File (.PL) ═══ The program library file contains groups of three lines. Each line has two components. The first is the file type (either module, objects, or functions) and is followed by the corresponding filename: Module filename.PLM Objects filename.PLO Functions filename.PLF Use blank lines to separate groups of file names. They are ignored by Visual PL/I. ═══ 26.2.2. C Constants File (.PLC) ═══ This file takes the form of a C file. For example, it contains multiple lines similar to the following example: Example of a C Constants File #define WC_MYCONTROL 0x45 ═══ 26.2.3. Function File (.PLF) ═══ The function file contains the code lines, code blocks, and comment lines, as described below. 1. Code lines: o A .PLF file can contain one or multiple code lines. o Each code line has up to four components, which you separate by one or more spaces. The first three components must be present; the fourth is optional. The components are in the following order: a. The name of the object file that contains the function. b. The function name. c. The function's parameters. d. A description of the function. This component is optional and can contain spaces. Example of a code line: listfunc.obj DrawListbox (hwnd,msg,mp1,mp2) Draw listbox item 2. Code blocks: A code block consists of a PL/I source program: o The first line of a code block contains: a. The name of the object file b. BEGIN c. The description of the code block o The second and following lines can be any valid PL/I source code. o The last line in a code block must be an END statement. ExampleofaCodeBlockENDStatement &&plicode.obj BEGIN END statement end; END 3. Comment lines: You can include comment lines in .PLF files that are recognized as such by Visual PL/I, but which are not included in the source code output generated by Visual PL/I. Such lines are identified by ·* in positions 1 and 2 of the source line. ═══ 26.2.3.1. Code Block Name Starting with && ═══ In the examples above, note that some code block names start with &&. An && prefix to the file name of a module description indicates that the module is only used internally by Visual PL/I and is not available for your use. Where && is prefixed to an object file name, no source code has been supplied for this code block, and the object module is supplied in only a precompiled and linkable form. In cases such as this, for example, &&lf.obj, there is no need to include the source file name or the compilation command line in order to compile the application. ═══ 26.2.4. Module File (.PLM) ═══ The module file contains one item per line. The module description appears first, and is followed by the names of the object files that contain the code blocks. The object file names must be on lines indented by at least one space, as shown in the following example. Example of a Module Description and Corresponding Object Files Sound Functions beep.obj Drag And Drop dragdrop.obj Use blank lines to separate groups of file names. They are ignored by Visual PL/I. ═══ 26.2.5. Object File (.PLO) ═══ The object file has three parameters on each line. The first is the object name. The second is the name of the source file. The third is a text string representing the command for compiling the source file. Each object file named in the .PLO file must have a corresponding line in the .PLF file, as shown below. Example of an Object File dragdrop.obj dragdrop.pli PLI beep.obj beep.pli PLI listfunc.obj listfunc.pli PLI pmfuncs.obj pmfuncs.pli PLI spinclas.obj spinclas.pli PLI &&pm.obj &&menu.obj &&pmg2.obj &&lf.obj &&but.obj Note: This file must include an entry for each object file listed in its associated .PLF file. Use blank lines to separate lines into groups. They are ignored by Visual PL/I. ═══ 26.2.6. PL/I Constants File (.PLP) ═══ This file takes the form of a PL/I file. For example, it contains multiple lines similar to the following example: Example of a PL/I Constants File dcl WC_MYCONTROL fixed bin(15) value ('45' xn); ═══ 26.3. Creating Your Own Code Block-An Example ═══ This example shows you how to create a code block that allows you to set the text in the title bar of a window. The code block consists of four files: o TITLEBAR.PL o TITLEBAR.PLO o TITLEBAR.PLM o TITLEBAR.PLF ═══ 26.3.1. TITLEBAR.PL File ═══ Example of a TITLEBAR.PL file contains the following: Example of a TITLEBAR.PL file Module titlebar.plm Objects titlebar.plo Functions titlebar.plf ═══ 26.3.2. TITLEBAR.PLO File ═══ Example of a TITLEBAR.PLO file contains the following: Example of a TITLEBAR.PLO file &&titlebar.obj ═══ 26.3.3. TITLEBAR.PLM File ═══ Example of a TITLEBAR.PLM File contains the name of the module that you select from the links dialog box in the Library list box. It represents the name of the code block that is called when this name is selected. Example of a TITLEBAR.PLM File TitleBar Functions &&titlebar.obj ═══ 26.3.4. TITLEBAR.PLF File ═══ Example of a TITLEBAR.PLF File contains the names of the associated source code that appears in the Code Block List list box within the Links dialog box. It is added to your program when you select it from this list. Example of a TITLEBAR.PLF File &&titlebar.obj BEGIN Set Titlebar Text .* Use this to set text in .... /* This code block sets the text in a window's titlebar */ call WinSetWindowText(WINDOW HANDLE, VARIABLE "Enter Titlebar Text in quotes."); END In Example of a TITLEBAR.PLF File, the comment line identified by .* is visible whenever you view the code through Visual PL/I. However, it is excluded from the source code generated by Visual PL/I for the application. The code block name is prefixed with && in the .PLO, .PLM, and .PLF files. ═══ 26.4. Inserting Variables into Code Blocks ═══ Visual PL/I allows a number of variables to be inserted into source code blocks. These variables control the output produced. When a code block is added to the project, it is checked for Visual PL/I's variables. Based on the variables present in the code block, Visual PL/I prompts you to select the appropriate parameter and then inserts it into the code block. Each variable type keyword has two components: o Variable type o Required attribute Note: Each variable keyword must be in uppercase in order to be parsed by Visual PL/I. ═══ 26.4.1. Specifying the Variable Type ═══ The variable type is one of the following, as shown in Variable Types in Code Blocks: ┌───────────────────────┬──────────────────────────────────────────────────────┐ │ VARIABLE TYPE │ DESCRIPTION │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ BITMAP │ Any bitmap on the currently selected window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ CHECKBOXES │ Selects more than one from a list of PM constants. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ CHILD │ Any secondary window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ CONTROL │ Any control on the currently selected window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ DIALOG │ Any dialog box. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ DLLDIALOG │ Selects a dialog from a DLL. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ DLLWINDOW │ Selects a window from a DLL. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ DLLGLOBALS │ Selects a global variable from a DLL. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ ICON │ Any icon created on the currently selected window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ KEYWORDSOFF │ Disables the parser - no attribute. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ KEYWORDSON │ Enables the parser - no attribute. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ MENU │ Any menu item on the menu attached to the currently │ │ │ selected window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ NUMBER │ Types numbers into the code. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ PMGPROMPT │ Adds prompt text to the next VISUAL PL/I dialog box │ │ │ that appears. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ SELECT │ Any of a list of PM constants. For example, SELECT │ │ │ CLR_ for a list of colors. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ SELECTMULTI │ Selects more than one from a list of PM constants. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ SYSTEM │ Internal Visual PL/I variables. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ STRING │ Types text into the code. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ TEXT │ Types lines of text into the code. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ THREAD │ Selects any thread. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ VARIABLE │ Types a variable into the code. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ WC_xxxxxxx │ Any controls on the currently selected window that │ │ │ are of a certain class. For example, WC_OX. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ WINDLG │ Any window or dialog box. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ WINDOW │ Any primary window (initially visible). │ └───────────────────────┴──────────────────────────────────────────────────────┘ Table 34. Variable Types in Code Blocks ═══ 26.4.2. Defining Attributes ═══ There are a number of attributes which qualify the above types shown in Variable Types in Code Blocks. No checking is performed on whether the attribute is valid in relation to the types. ┌───────────────────────┬──────────────────────────────────────────────────────┐ │ ATTRIBUTE │ DESCRIPTION │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ ASCIIDATA │ Generates the spin button's default ASCII data. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ ATTRIBUTE │ Generates the menu's attribute value. For example, │ │ │ MIA_CHECKED. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ CLASS │ Generates the class of the window. For example, │ │ │ WC_LISTBOX or PMGWindowClass. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ CLHANDLE │ Produces hwndcnn, where nn is the number of the │ │ │ item. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ FILENAME │ Filename of the output code, which is used by SYSTEM │ │ │ only. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ FCFFLAGS │ Produces the FCF_s needed to create the specified │ │ │ window. For example, FCF_TITLEBAR | FCF_MENU | │ │ │ FCF_SIZEBORDER. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ FCFFLAGSCOMMA │ Produces the FCF_s needed to create the specified │ │ │ window. For example, FCF_TITLEBAR , FCF_MENU , │ │ │ FCF_SIZEBORDER. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ FCFVAR │ Generates flCreatenn, where nn is the number of the │ │ │ item. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ HANDLE │ Either hwndnn for windows, or hbitnn for │ │ │ bitmaps/icons, where nn is the number of the item. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ ID │ Produces the ID of the object, such as WINDOW, ICON, │ │ │ BITMAP, MENU, or CONTROL. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ INDEX │ Produces a unique number based on the │ │ │ WINDOW/CONTROL/MENU given. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ INITIALVALUE │ Generates the spin button's initial value. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ LENGTH │ Length of the window text. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ LOWERVALUE │ Generates the spin button's lower value. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ MODULEHANDLE │ Generates a variable name of the following hModxxxx, │ │ │ where xxxx is the file name of the project. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ NEW │ Asks for a new item of the same previous type. For │ │ │ example, WC_LISTBOX ID,WC_LISTBOX NEW,WC_LISTBOX ID │ │ │ would produce 'LI_1,,LI_2'. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ NO │ Produces the actual numeric value of the identifier. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ PARENT │ Either HWND_DESKTOP for primary windows or hwnd for │ │ │ others. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ POINTL │ ICON/BITMAP uses POINTL to generate hplnn, where nn │ │ │ is the number of the item. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ PROCEDURE │ Either Winprocnn or DlgProcnn, where nn is the │ │ │ number of the procedure. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ RECTL │ Generates rectlnn, where nn is the number of the │ │ │ item. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ STYLE │ Produces the style of the window. For example, │ │ │ WS_VISIBLE | BS_AUTOCHECKBOX for an autocheckbox. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ STYLECOMMA │ Produces the style of the window. For example, │ │ │ WS_VISIBLE , BS_AUTOCHECKBOX for an autocheckbox. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ TEXTLENGTH │ Produces the length of the CONTROL/WINDOW/MENU's │ │ │ text. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ "text string" │ Adds prompt text, using STRING, NUMBER, VARIABLE, │ │ │ and TEXT. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ TITLE │ Title of the window. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ UPPERVALUE │ Generates the spin button's upper value. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ VARLENGTH │ Produces the length of the entry fields variable. │ └───────────────────────┴──────────────────────────────────────────────────────┘ ┌───────────────────────┬──────────────────────────────────────────────────────┐ │ ATTRIBUTE │ DESCRIPTION │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ VARNAME │ Produces the name of the entry fields variable or │ │ │ the name of a imported global variable. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ XPOS │ X coordinate. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ YPOS │ Y coordinate. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ XPOSMAP │ X coordinate in dialog unit. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ YPOSMAP │ Y coordinate in dialog units. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ XSIZE │ X size. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ YSIZE │ Y size. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ XSIZEMAP │ X size in dialog units. │ ├───────────────────────┼──────────────────────────────────────────────────────┤ │ YSIZEMAP │ Y size in dialog units. │ └───────────────────────┴──────────────────────────────────────────────────────┘ Table 35. Attributes ═══ 26.5. Setting Up Local and Global Variables ═══ You can add text into the local variable area of a window/dialog procedure and also add code into the main() function. This section describes how to complete each of these activities. ═══ 26.5.1. Specifying Local Variables ═══ The Visual PL/I variable qualifier LOCALVAR enables you to add code to the local variable area of your window procedure. Visual PL/I scans your project for all LOCALVAR variables added to items within a particular window, sorts them, and adds one copy of all duplicate LOCALVAR lines found. This enables you to add a local variable to a code block, even if a duplicate definition of this variable is created. Example of Code for Adding a Local Variable to a Code Block &&color.obj BEGIN Set Control Color (Background) LOCALVAR dcl lColorIndex LONG; /* ULONG indicating color */ PMGPROMPT "Select a color and press OK" lColorIndex = SELECT CLR_; /* Set the background color of CONTROL ID */ call WinSetPresParam(WinWindowFromID(hwnd0, CONTROL ID), PP_BACKGROUNDCOLORINDEX, stg(LONG), addr(lColorIndex)); END Rules for Local Variables When adding local variables, the following rules apply: o The keyword LOCALVAR must start in column 1. o The text following the LOCALVAR keyword must match similarly declared LOCALVAR lines in other code blocks. o Spaces and comments are ignored by Visual PL/I when it searches for duplicate text strings in the source code. You can initialize a local variable in the LOCALVAR declaration. For example: LOCALVAR DCL LcolorIndex LONG init(0); However, a local variable must not be initialized more than once in a project, or a compilation error will occur. ═══ 26.5.2. Specifying Global Variables ═══ You can use global Visual PL/I variables to add code to the main procedure in your project. Visual PL/I scans the project for all global variables added to items in it, sorts them, and adds one copy of all duplicate global lines found. The global variables are listed below: o HASH_DEFINES o HASH_INCLUDES o PROTOTYPES o GLOBAL_HANDLES o GLOBAL_VARIABLES o MAIN o LOCAL_VARIABLES o INITIALIZE o WIN INITIALIZE o CREATE_MSG_QUEUE o REGISTER_CLASS o SET_FLCREATE o CREATE_STD_WINDOW o SET_WINDOW_POS o MESSAGE_LOOP o DESTROY_WINDOWS o DESTROY_MSG_QUEUE o TERMINATE_A o WIN TERMINATE_A o TERMINATE_B o INITFUNCTION Example of a Skeleton Code Block Containing Global Variables contains a skeleton code block showing some of the above global variables: Example of a Skeleton Code Block Containing Global Variables ·* ·* One PROTOTYPES per line PROTOTYPE DCL MyFunction(HWND) APIENTRY; ·* ·* One GLOBAL_HANDLES per line /* Handle for Main Frame Window*/ GLOBAL_HANDLES dcl hwndMyFrameWindow HWND; ·* ·* One GLOBAL_VARIABLES per line /* Handle for Main Msg Queue */ GLOBAL_VARIABLES dcl MYMSGQHANDLE QMSG; ·* ·* One LOCAL_VARIABLES per line /* Flags for the Main Frame */ LOCAL_VARIABLES dcl ulFrameFlag ULONG; ·* ·* MAIN could go here ·* ·* INITIALIZE one per line ·* Inserts the line immediately after the WinInitialize call INITIALIZE call MyInitialize; /* Call my initialization */ ·* ·* TERMINATE_A one per line ·* Places code immediately after the WinTerminate statement ·* ·* TERMINATE_B one per line ·* Places code before END of main procedure ·* END MAIN; In Example of Global Variable Used in Code Block, a global variable is used where a code block requires that an initialization function is called in order for the code block to work properly: Example of Global Variable Used in Code Block &&plicode.obj BEGIN GLOBAL Char Variable GLOBAL_VARIABLES dcl VARIABLE "Variable name " char(NUMBER "Variable Length") varz ; END ═══ 26.6. Changing the Way Bitmaps are Handled ═══ Visual PL/I assumes that you want all bitmaps to be displayed in the size that you initially added them to the window. You can do this only by generating code that actually paints the bitmaps into their respective windows. If you want bitmaps to be treated the same as other controls and created as actual controls in the window, you must read in the program library file, PMGBIT.PL. Then, when the project is run, the bitmaps appear in the exact size in which they were created by the bitmap editor program. ═══ 26.7. Adding Prompts to Code Blocks ═══ The PMGPROMPT keyword enables code block writers to display more meaningful prompts for the dialogs. Example of PMGPROMPT Keyword PMGPROMPT "Please select a color" SELECT CLR_ Example of PMGPROMPT Keyword displays Please select a color in the dialog with a list of CLR_xxx constants. The PMGPROMPT keyword acts only on the next Visual PL/I keyword that occurs in the code block. Do not declare variables whose uppercase counterparts are spelled the same way. The macro facility in the following example replaces hwnd and causes a compilation error: dcl hwnd HWND; Instead, do the following: dcl hwnd0 HWND; ═══ 27. Error Messages ═══ This section lists Visual PL/I error messages. Cannot create window An unknown error occurred when creating a window. Check the styles panel for any illegal style combination. Cannot open file XXXX Visual PL/I encountered an error when reading or writing the file. Check that the file name is valid or that there is enough space free on the disk. Cannot change directory to XXXX The directory typed does not exist. Retype a valid directory path. Error in .pl file XXXX The .pl files contains a keyword that is not valid. Library failure XXXX An error occurred when reading in a .pl file. Cannot run XXXX An error occurred when Visual PL/I was trying to execute another program. Check that the path is correct and that the program exists. No object module definition for XXXX. Adding a temporary one. A code block was found with no object module defined. A temporary definition was added to Visual PL/I's list for this invocation of the program. Check the .pl? files for any incorrect object definitions. Bad file name XXXX The file name typed is not a valid. Illegal entry for #define XXXX The identifier entered does not conform to the naming rules for PL/I constants. Library failure - cannot link XXXX An error occurred when reading a link in. Check that the code block has not been drastically modified since the last time the project was read. Cannot delete - item is referenced XXXX You cannot delete an item (control/window) until all code blocks referencing it have been removed. Cannot find function XXXX A code block was found in a project with no matching code block in the current libraries. Read in the library file containing that code block. Cannot have two links dialogs present The links icon was dropped on a window while another links dialog was still visible. Dismiss the first dialog and retry. Code blocks are too big (>30k) The total amount of code attached to a single message exceeded the limit for Visual PL/I Different number of parameters in file XXXX A code block in a library has been modified and parameters have either been removed or added. This causes any projects that use them to have an incorrect number of parameters. Recreate the links affected to ensure the number and type of parameters match up. Incompatible parameters in file XXXX A code block in a library has been modified and parameters have been changed from one type to another. This causes any projects which use them to have mismatched parameters. Recreate the links affected to make sure the parameters match up. Visual PL/I is running out of memory Visual PL/I is running out of memory. Close down some other application and continue. This error will occur 4 times before Visual PL/I runs out of memory and ends. Visual PL/I has run out of memory A fatal memory error occurred from which Visual PL/I cannot recover. Unknown Visual PL/I variable XXXX A code block contains an unknown variable. The action bar must be in the same project as the window You cannot add an action bar to a window without first adding it to the project. Please copy menu or remove it from existing window before using it. An action bar can only be attached to one window at a time. ═══ 28. Bibliography ═══ ═══ 28.1. IBM PL/I for OS/2 Publications ═══ Fact Sheet, GC26-8005 License Information, GC26-8004 Installation, SX26-3833 Programming Guide, SC26-8001 Language Reference, SC26-8003 Built-In Functions, SC26-8089 Reference Summary, SX26-3832 Messages and Codes, SC26-8002 WorkFrame/2 Guide, SC26-8000 ═══ 28.2. IBM SAA AD/Cycle PL/I MVS & VM Publications ═══ Installation and Customization under CMS, SC26-3120 Installation and Customization under MVS, SC26-3119 Language Reference, SC26-3114 Compile-Time Messages and Codes, SC26-3229 Diagnosis Guide, SC26-3149 Migration Guide, SC26-3118 Programming Guide, SC26-3113 Reference Summary, SX26-3821 ═══ 28.3. IBM OS PL/I Version 2 Publications ═══ Programming Guide, SC26-4307 Programming: Language Reference, SC26-4308 Programming: Reference Summary, SX26-3759 ═══ 28.4. IBM OS/2 2.0 Technical Library ═══ The following books comprise the OS/2 2.0 Technical Library (10G3356). Application Design Guide, S10G-6260 Programming Guide, Volume 1, S10G-6261 Programming Guide, Volume 2, S10G-6494 Programming Guide, Volume 3, S10G-6495 Information Presentation Facility Guide and Reference, S10G-6262 System Object Model Guide and Reference, S10G-6309 Control Program Programming Reference, S10G-6263 Presentation Manager Programming Reference Volume 1, S10G-6264 Presentation Manager Programming Reference Volume 2, S10G-6265 Presentation Manager Programming Reference Volume 3, S10G-6272 Physical Device Driver Reference, S10G-6266 Virtual Device Driver Reference, S10G-6310 Presentation Manager Driver Reference, S10G-6267 Procedures Language 2/REXX Reference, S10G-6268 Procedures Language 2/REXX User's Guide, S10G-6269 ═══ 29. Glossary ═══ This glossary contains terms that have specific meanings for Visual PL/I. If you do not find the term you are looking for, refer to IBM Dictionary of Computing, ZC20-1699. ═══ 29.1. button ═══ button Type of control that can be added to a window. There are three kinds of buttons available: push buttons, radio buttons, and icon buttons. ═══ 29.2. check box ═══ check box A two-part control consisting of a square box and choice text. A check box acts like a switch. ═══ 29.3. code block ═══ code block Segment of code that can be added to a Visual PL/I program to perform a particular function. Visual PL/I supplies a set of code blocks and you may also add your own code blocks. ═══ 29.4. combination box ═══ combination box A control that combines the capabilities of an entry field and a list box. ═══ 29.5. container ═══ container A collection of records for holding data. Categories of data are presented as objects to the user. ═══ 29.6. context menu ═══ context menu Menu of options that may be performed on a window or control created with Visual PL/I. The context menu provides you with a fast way of selecting the options. It may be displayed by selecting the window or control and pressing mouse button 2. ═══ 29.7. controls ═══ controls Provide users with the means to make choices and enter information from a window. ═══ 29.8. dialog box ═══ dialog box Appears when a user selects an option from a menu or presses a push button. ═══ 29.9. entry field ═══ entry field Accepts information typed by the user. An entry field is either single line or multi-line. ═══ 29.10. folder ═══ folder A container object used to store and organize objects. ═══ 29.11. graphical user interface (GUI) ═══ graphical user interface (GUI) A type of computer interface of a desktop. Within that desktop are icons, representing actual objects, that the user can access and manipulate with a pointing device, such as a mouse. ═══ 29.12. grid ═══ grid Network of uniformly spaced dots in horizontal and vertical lines. It may be displayed on a window to assist you in the positioning and sizing of controls. You may also specify the spacing to be used in the grid. ═══ 29.13. group box ═══ group box A rectangular box drawn around a group of related controls. ═══ 29.14. icon button ═══ icon button A button with a graphic inside that depicts an action. ═══ 29.15. icon format ═══ icon format Default display for Visual PL/I. Projects, windows, menus, and controls are represented by an icon and text. ═══ 29.16. list box ═══ list box A rectangular box with scroll bars, from which the user can select one choice. ═══ 29.17. mark ═══ mark Method for selecting controls to be affected by layout options. ═══ 29.18. menu attribute ═══ menu attribute Characteristic that are assigned to a menu item to control its status. For example, if you select MIA_HILITED, the state is TRUE only when the item is selected. ═══ 29.19. menu style ═══ menu style Characteristic that are assigned to a menu item to control its appearance or behavior. For example, if you select MIS_STATIC, the item exists for information purposes only. It cannot be selected with the mouse or keyboard. ═══ 29.20. notebook ═══ notebook Simulates a real world notebook by allowing the user to select information quickly. It contains pages and tabs to organize information, and has a binding and back page for a three-dimensional effect. ═══ 29.21. Presentation Manager ═══ Presentation Manager The interface of the OS/2 operating system that presents, in windows, a graphics-based interface to applications and files installed and running under the OS/2 operating system. ═══ 29.22. primary window ═══ primary window Main work area for an application. It is not tied to any other window or object. ═══ 29.23. project ═══ project Container for interface components. You must open a project for each interface you design and for each application you develop. You may also use a project to hold standard interface components. ═══ 29.24. project file ═══ project file File that holds the contents of a project. Visual PL/I gives each project file a suffix of ·prj. ═══ 29.25. push button ═══ push button A rounded corner rectangle with text inside that describes an action. ═══ 29.26. radio button ═══ radio button A two-part symbol consisting of a circle and choice text. ═══ 29.27. rectangle ═══ rectangle A graphic component that groups or divides controls on a window. ═══ 29.28. scroll bar ═══ scroll bar Allows the user to see information that is not visible on the window component. ═══ 29.29. secondary window ═══ secondary window Allows an application to present information related to a particular subject. A secondary window is accessed from a primary window. ═══ 29.30. slider ═══ slider Displays values that are represented graphically by measurements at increments. A slider allows the user to set or display a value by moving an "arm" along a shaft, while holding down the mouse button. ═══ 29.31. spin button ═══ spin button Enables the user to complete an entry field by scrolling through a ring of related choices. ═══ 29.32. static text ═══ static text Adds information or descriptions anywhere in a window. ═══ 29.33. system bitmap ═══ system bitmap OS/2 system bitmap that may be imported into Visual PL/I. ═══ 29.34. system icon ═══ system icon OS/2 system icon that may be imported into Visual PL/I. ═══ 29.35. text format ═══ text format Method of display for Visual PL/I where projects, windows, menus, and controls are represented only by text. You can customize Visual PL/I by changing from the default display of icon with text to a text only display. ═══ 29.36. value set ═══ value set Allows the user to select an item from a set of graphical choices. ═══ 29.37. window ═══ window A user interface that displays information in a rectangular area on the screen. In these areas, an application displays information and receives input from a user. ═══ 29.38. window style ═══ window style Characteristic that are assigned to a window or control to control its appearance or behavior. For example, if you select WS_MAXIMIZED, it creates the window maximized. ═══ 30. Readers' Comments ═══ PL/I for OS/2 Toolkit Reference Version 1 Release 1 Document Number: SC26-8223-00 Please use this form only to identify online information errors or to request changes in this information. Direct any requests for additional hardcopy publications, technical questions about IBM systems, changes in programming support, and so on, to your IBM representative or to your nearest IBM branch office. You may use this form to communicate your comments about this information, its organization, or subject matter with the understanding that IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. To use this form, print this panel by selecting Print from the Services menu in the Help window. Select This section to have just this form print out. Mail the completed form to: IBM Corporation, Department J58 P.O. Box 49023 San Jose, CA, 95161-9023 United States of America If your comment does not need a reply (for example, pointing out a typing error), do not include your name and address below. If your comment is applicable, we will include it in the next revision of the manual. If you would like a reply, be sure to print your name and address below. You can also send your comments by facsimile to (800) 426-7773 addressed to the attention of the RCF Coordinator. If you have access, you can send your comments electronically via: INTERNET, to comments@vnet.ibm.com IBMMAIL, to USIB5TNP If you choose to respond through Internet, please include either your entire Internet network address, or a postal address. Be sure to include the following with your comments: o Title and publication number of this book o Page number or topic to which your comment applies