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

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

/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / docs / toolinfo.inf (.txt) < prev next >

Wrap

OS/2 Help File | 1993-07-30 | 380.2 KB | 15,149 lines

ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Shortcut Look under this heading for the name of the specific tool you are using or a more specific topic. ΓòÉΓòÉΓòÉ <hidden> Double-Byte Character Set (DBCS) ΓòÉΓòÉΓòÉ Throughout this document, you will see references to specific values for character strings. These values are for single-byte character set (SBCS). If you use the double-byte character set, note that one DBCS character equals two SBCS characters. ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ Trademark of the IBM Corporation ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ Microsoft is a trademark of the Microsoft Corporation. Windows is a trademark of the Microsoft Corporation. CodeView is a trademark of the Microsoft Corporation. ΓòÉΓòÉΓòÉ 1. How to Use ΓòÉΓòÉΓòÉ Select One: Introduction How to Use Action Bar Choices How to Use the Programming Information Error Messages Double-Byte Character Set ΓòÉΓòÉΓòÉ <hidden> Tools Reference - Introduction ΓòÉΓòÉΓòÉ The OS/2* 2.0 Tools Reference is a technical reference for the OS/2 tools. It gives reference information and code examples to enable you to write programs, and create icons, fonts, and dialog boxes. Before you begin to use this information, you should 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 menu bar choices o Use the programming information. Using the Contents. In the Tools Reference, each tool is listed as a different topic in the Contents panel. 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). Getting 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, depending on your display device. 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. ΓòÉΓòÉΓòÉ <hidden> Tools Reference - Using Menu Bar Choices ΓòÉΓòÉΓòÉ Several choices are available for managing information presented in the OS/2* 2.0 Tools Reference. There are three pull-down menus on the menu bar: the Services menu, the Options menu, and the Help menu. The actions that are selectable from the Services menu operate on the active window 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. 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 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 keys 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 document Contents list, 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. You will find this 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 Copy copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager* (PM) editor (for example, the System 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 Copy to file copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. You will find TEXT.TMP in the directory where your viewable document resides. To copy 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 named TEXT.TMP. For information on one of the other 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 one of the other 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). ΓòÉΓòÉΓòÉ <hidden> Tools Reference - Using Tools Information ΓòÉΓòÉΓòÉ The Tools Reference consists of reference information that provides a detailed description of each OS/2 tool, except the SOM Compiler and IPF Compiler, which are referenced in their own online documents. Reference information is presented by tool name. For example: ΓòöΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòù Γòæ Contents Γòæ ΓòáΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòú Γòæ How to Use Γòæ Γòæ Dialog Editor Γòæ Γòæ Font Editor Γòæ Γòæ Icon Editor Γòæ Γòæ EXEHDR Γòæ Γòæ . Γòæ Γòæ . Γòæ Γòæ . Γòæ Γòæ Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ By clicking on the plus sign beside 'Icon Editor', you see the introductory panel for the Icon Editor online documentation. Selecting a highlighted reference anywhere in the documentation for any tool takes you directly into the information for that topic. Reference information is presented in IPF windows that can be sized, moved, minimized, maximized, or closed. When you select a tool, you will see two windows displayed: ΓòöΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòªΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòù Γòæ LINK386 Γòæ LINK386 - Introduction Γòæ ΓòáΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¼ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòú ΓòæIntroduction ΓòæLINK386 is used to combineΓòæ ΓòæRunning LINK386 Γòæobject files... Γòæ ΓòæLINK386 FeaturesΓòæ Γòæ ΓòæLINK386 Syntax Γòæ Γòæ Γòæ . Γòæ Γòæ Γòæ . Γòæ Γòæ Γòæ . Γòæ Γòæ Γòæ Γòæ Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò⌐ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ The window on the left is the primary window. It contains a list of items that are always available to you. On the right is the secondary window, which contains a 'snapshot' of selected information. Descriptions of individual functions include the syntax. All of the information needed to understand a topic is readily available to you through the primary window. The information is divided into discrete information groups, and only the appropriate information group appears for the topic that you are viewing. The information groups for a reference unit (that is, a function description) can include the following: o Introduction o Syntax o Options o Examples This list may vary. Options, for instance, may be omitted when they do not apply. In other instances, information may be added when appropriate. For example, when viewing NMAKE, Command Files and Macro Definitions are among the additional topics listed in the primary window. When viewing a secondary window, you may want to view another referenced window. For example, when viewing LINK386 Options, you can double click on any option listed in that window, to view the description and syntax of the option. Each window can be individually closed. All windows are closed when you close the primary window. Some topics may not necessarily fit into the small window size on your screen. You may maximize the secondary window for better readability. ΓòÉΓòÉΓòÉ <hidden> Tools Reference - Error Messages ΓòÉΓòÉΓòÉ Some tools generate error messages that may be encountered when building an application. Included is a brief description of the action required to correct the error. Error messages for the following utilities are listed: o LINK386 Error Messages o RC (Resource Compiler) Error Messages o IMPLIB Error Messages o MKMSGF Error Messages o MSGBIND Error Messages ΓòÉΓòÉΓòÉ 2. Dialog Editor ΓòÉΓòÉΓòÉ Select One: Introduction Adding Controls Arranging Controls Changing a Dialog Creating a Dialog Designing a Dialog Sample Template Ending an Edit Session Ordering Control Groups Selecting Color and Font Testing the Dialog Using a Grid Using the Options Menu ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Introduction ΓòÉΓòÉΓòÉ You can use the Dialog Editor not only to create and modify dialog boxes, but also to create and modify the controls and text within dialog boxes. As you create the dialog box and its controls you see them on the screen as the user sees them when your program is run. You can place each dialog box and its controls where you want them on the screen. In addition, you can test the dialog box in a simple way before you incorporate it into your application. Each dialog box and control can have either an integer identifier or a symbolic identifier that equates to an integer identifier, either of which you can use in your application to refer to the dialog boxes or controls. If you intend using symbolic identifiers in your application, you must enter the symbolic and integer identifiers in an include file. If you do not use symbolic names, the Dialog Editor supplies an integer identifier for each control, and for the dialog box itself. You can use the Dialog Editor to create the include file, or you can use a text editor to create the include file before using the Dialog Editor. It is good programming practice to plan the resources that your application will use, and choose a naming and numbering convention for the symbolic or integer identifiers before you create them. You should keep the include file separate from other include files used by your application. Include files used by the Dialog Editor can contain only #define statements that define their symbolic identifiers and equivalent integers. Although the Dialog Editor draws dialog boxes and controls on the screen so you can see what they look like when used by your application, it does not save them as graphics. Instead, the Dialog Editor saves them in an ASCII-text format file, that has a .DLG extension. This is the dialog template. The Dialog Editor also creates a compiled form of the .DLG file, in a file with a .RES extension. The .DLG and .RES files can contain more than one dialog box. The resource file may contain other application resources, such as icons, bit maps, and string tables. It is attached to the application's executable (.EXE) file during the compile and link process. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Designing Dialog Boxes ΓòÉΓòÉΓòÉ Dialog boxes should be designed to clearly identify the information that the user is required to complete. The following are a few Common User Access* guidelines: o Lay out the controls in columns, starting at the upper-left corner, for left to right or top to bottom scanning. o Vertically and horizontally align selection and entry fields so that the cursor moves in a straight line. o Arrange the controls in the sequence in which the user would complete them. o If there are only a few entry fields, locate them at the top of the dialog box. o Make groups of controls obvious by use of group boxes and white space. o Align group boxes, where possible. Group boxes can be extended to the right to line up with other group boxes. o Use field identifiers to identify the purpose of single and multiple groups of choices. For further information regarding dialog boxes, refer to the Common User Access publications. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Creating a Dialog Box ΓòÉΓòÉΓòÉ To run the Dialog Editor, select Dialog Editor from the Development Tools group. The main window appears, displaying the menu bar choices File, Edit, Arrange, Control, Options, and Help. Online help that tells you how to use the editor can be accessed from most Dialog Editor windows. To create a new dialog box, start with either one of the following steps: o Select New Dialog from the Edit menu. The editor opens new files with the extensions .RES and .DLG. This also opens a new include file. o Select New from the File menu. This opens new resource files with the extensions .RES and .DLG. You can open a new include file or an existing one. Both of the above steps have the same effect. When you edit a dialog box, the names of the resource and include files are shown in the title bar of the Dialog Editor. If you are editing a new file that has not yet been named or saved, (Untitled) appears in the title bar in place of a name. If (Untitled)* appears in the title bar in place of a name, there are unsaved changes. The Dialog Box ID field appears in the status area. A default integer number is supplied in the entry field. Type a symbolic identifier for the dialog box, such as MYDIALOG. Tab to the integer field and type the integer number. Press Enter to place them both in the include file. The new dialog box appears in the lower-left corner of the editor screen enclosed by a frame, which allows you to change the width and height of the selected item. This indicates that the dialog box is selected for editing. If you are creating a new dialog box, the dialog is automatically selected; at all other times, before you edit the dialog box or a control, you must click on it to select it. The To continue creating the new dialog box, follow these steps: 1. Make the dialog box larger by clicking on its borders and dragging until the box is the size you want it to be. This can be done in one operation by clicking on the upper-right corner of the frame and dragging diagonally upwards and to the right. Information about the item you are editing is displayed in the Selected Item Status box in the left half of the status area. As you move the shadow box, the x-y-coordinates change. These are the coordinates of the origin of the dialog box relative to the origin of the window. The cx-cy-coordinates are the width and height of the dialog box. The symbolic identifier is also shown. 2. Select Styles from the Edit menu. The Dialog Box Styles pop-up window appears. 3. Click on the text entry field in the status area, and then type the dialog box title (for instance, Sample dialog box) into the field. 4. Press Enter and the title appears at the top of your dialog box. You can reposition the entire dialog box by moving the pointer inside the top area enclosed by the frame, holding the mouse button down, and dragging the shadow box across the screen. When the shadow box is in the position where you want the dialog box to appear, release the mouse button. The dialog box appears in that position. Alternatively, you can move the dialog box using the keyboard arrow keys. You can reposition the dialog box at any time during the edit. You now have your dialog box, and are ready to start adding controls, but you may want to first select the grid option to make laying out your dialog easier. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Selecting Color and Font ΓòÉΓòÉΓòÉ The Presentation Parameters dialog allows you to select color and font for individual controls or for an entire dialog box. You can select all of the following: o Foreground Color o Background Color o Foreground Color Highlight o Background Color Highlight o Disabled (greyed out) Foreground Color o Disabled (greyed out) Background Color o Font Size o Font Name To set presentation parameters, follow these steps: 1. Select a control or the dialog box. 2. Select Presentation Parameters on the Edit menu. 3. Type the number, from 1 to 255 parts of each color, in the appropriate fields. 4. Type the font and size, if you want to change the default, in the last two fields. 5. Select OK or press Enter to close the dialog. You may now want to test the dialog. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Arranging Controls ΓòÉΓòÉΓòÉ The Arrange menu allows you to arrange and align controls in a logical and easy-to-understand layout. Align Allows you to align controls along an edge Even spacing Allows you to evenly space controls Same size Allows you to set controls to the same size Push buttons Allows you to arrange push buttons Order groups Displays the Group/Control Ordering dialog, which allows you to change the order of controls and groups. See Ordering Control Groups for additional information. Settings Displays the Arrange Settings dialog, which allows the grid and spacing constants to be changed. See Using a Grid for additional information. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Using a Grid ΓòÉΓòÉΓòÉ Controls are placed in a dialog box using the mouse, and can be moved in line with each other also using the mouse. However, controls can be positioned more accurately using the keyboard arrow keys or mouse after grid values have been set. The Arrange Settings dialog lets you set the number of character spaces (in dialog units) by which you can move dialog boxes and controls when using the Dialog Editor. To set the grid size, follow these steps: 1. Select Settings from the Arrange menu. The Arranging Settings dialog is displayed. The initial grid setting for both x and y is 1 unit. 2. Change the x-setting to 10 and the y-setting to 5. Click on OK. The horizontal (x) and vertical (y) values are in dialog units. A horizontal dialog unit is 0.25 of the standard character size. A vertical dialog unit is 0.125 of the standard character size. For example, if you move a control to the left or the right (using the mouse or keyboard arrow keys) with x set at 20, it moves in steps of twenty dialog units. When you subsequently position dialog boxes or controls, the objects move by the specified number of dialog units on an invisible grid. Large values make it easier to align controls, while small values allow you to position controls in the dialog box more precisely. Now that the grid is in place, you are ready to start adding controls. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Ordering Control Groups ΓòÉΓòÉΓòÉ This option allows you to gather controls into groups and to change the order in which the tab keys and arrow keys move the selection cursor around the controls. When you use group boxes to group controls, always create the group box before the controls that are to go inside it. It is good practice to put group markers around all separate groups of controls, including putting a marker before the first control in the list. The list box shows the order in which the selection cursor moves between the controls when the user presses the arrow and tab keys. (The coordinate position of a control when displayed in the dialog box does not affect the order.) Initially, the controls are listed in the order in which they were created. There are three functions involved in grouping controls: o Setting Group Markers o Setting Tab Markers o Moving Control Order Setting Group Markers To set up groups, follow these steps: 1. Select Order Groups from the Arrange menu. The Groups - order dialog is displayed. 2. Click the pointer on the first radio button in the list box. 3. Click on the Group Marker pushbutton. A group marker is now displayed between the Text control and the first radio button in the list. 4. Scroll down the list and click on the first pushbutton in the list. Click on the Group Marker pushbutton. This has organized your controls into groups of text, radio buttons, check boxes, and pushbuttons. Setting Tab Markers After setting group markers, you will want to set tab-stops. The controls marked with an asterisk already have tab-stops. To make the tab stop at only the first control in each group, delete the tab-stops from the second and third radio button and check box, following these steps: 1. Click on the second radio button in the list to mark it 2. Click on the Delete Tab pushbutton. 3. Repeat the above steps for the third radio button, and then perform the same operation for the second and third check box in the list. When this is complete, press Enter. Moving Control Order You can move controls in the list to see how the changes affect the movement of the cursor during testing. To change the position of a control in the list, follow these steps: 1. Click on the control's name to select it. 2. Position the pointer in the list where you want the name to appear. The pointer changes shape to a short horizontal line when it is over a place where you can insert the name. 3. To insert the control name, click the mouse button. After grouping controls, you may now want to test or edit the dialog, or enter additional controls. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Adding Controls ΓòÉΓòÉΓòÉ The control menu lists, in alphabetical order, all the controls that you can put in a dialog box. To add controls, follow these steps: 1. Select a control on the Control menu or use the shortcut: Shortcut: You can select any control by clicking on its icon on the Control Palette at the right side of the window. The pointer becomes a small plus sign (+) in a square. The center marks the position where the lower-left corner of the control's frame will be set. 2. Click the mouse to position the control. 3. A dialog may appear (depending on the type of control) in which you must enter data or check preferences to define the control. Complete this and close the dialog. For an example of adding controls in a typical dialog, see Adding Controls Example. You may now want to test the dialog. For detailed descriptions of individual controls and how they work, see the individual controls in the online help (while using the Dialog Editor) by following these steps: 1. Select Help Index on the Help menu (or press F1 and select Help Index.) 2. Select Options or press Alt-O. 3. Select Contents or press Ctrl-C. 4. Select Control Menu for an alphabetical list of controls, or Control Palette for the icons as they appear on the Control Palette. 5. Select the control you want to read about. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Adding Controls Example ΓòÉΓòÉΓòÉ The control menu lists, in alphabetical order, all the controls that you can put in a dialog box. To add controls for a sample dialog, follow these steps: 1. Select Text on the Control menu or use the shortcut: Shortcut: You can select any control by clicking on its icon on the Control Palette at the right side of the window. The pointer becomes a small plus sign (+) in a square. The center marks the position where the center of the control will be. 2. Position the pointer inside the dialog box near the upper-left corner and click the mouse. 3. Type Student Level: in the Text entry field. Observe that the next sequential integer is supplied in the Symbol entry field. Press Enter. 4. Replace the symbol with ID_GRAD and press Enter. The editor assigns the next integer to the symbolic identifier you entered, and places it in the include file. This is another technique for entering symbolic identifiers. 5. To view or change the include file at any time, select Symbols from the Edit menu. The Symbols dialog appears. The symbolic and integer identifier for the dialog box and the text control are displayed in the list box. The dialog allows you to add, delete, and change the identifiers, and view the hexadecimal equivalents of the integers. 6. Select the OK push button to remove the dialog and register any changes. Select Cancel if you have not made any changes. 7. In your dialog box, the static control is not large enough for you to see all the text. To remedy this, click on the text, and a frame appears around it. Drag the right-hand edge of the frame to the right to enlarge the field. When you release the mouse button you should be able to see all the text. When a control has a frame around it, it is selected and you can use a shadow box to position it, as you did with the dialog box. 8. To add another control, select Radio Button from the Control menu and position the cursor just beneath the Student Level text. Press Enter. 9. Type Elementary in the Button Text entry field and press Enter. Drag the right edge of the frame that surrounds the radio button until you can see all of the text. 10. Select Radio Button again and type Intermediate in the Text entry field. Position this radio button below the first one. 11. Select Radio Button again and type Advanced in the Text entry field. Position this radio button below the other two. 12. Select Group Box from the Control menu. Position the cursor to the right of the column of radio buttons and press Enter. 13. Type Media in the Text entry field and press Enter to title of the group box. 14. Click on the lower-right corner of the group box frame and drag it diagonally down and to the right to enlarge it. The bottom of the group box frame should be lower than the last of the radio buttons, and the right-hand side of the group box should be almost at the far right of the dialog box. This is to make room for a group of check boxes that will go inside the group box. When you use group boxes to group controls, you always create the group box before the controls that are to go inside it. 15. Select Check Box from the Control menu. Position the cursor inside the group box in line with the first radio button in the list and click the mouse. 16. Type Text Books in the Button Text entry field and press Enter. Enlarge the frame of the check box until all of the text is displayed. 17. Select Check Box again and position the cursor below the first check box. Type Video in the Text entry field and click Enter. Enlarge the check box frame until all of the text is displayed. 18. Select Check Box again and position the cursor below the previous two check boxes. Type Diskettes in the Text entry field. In the left-hand side of the dialog box you should now have a column of radio buttons with a heading of Student Level, and on the right a group box with a heading of Media and containing three check boxes. 19. Finally, add three pushbuttons to the dialog box. Select Pushbutton from the Control menu. Position the cursor in the lower-left side of the dialog box and click the mouse. Type OK in the Text entry field. and press Enter. 20. Position another push button to the right of the first one (in the lower middle of the dialog box) and type Cancel in the Text entry field. 21. Select a third push button and position it to the right of the second Type Help in the Text entry field. The dialog box and its controls are now complete. Try selecting each of the controls, and observe the information in the Selected Item Status. It holds information about each control that you edit. You may now want to test the dialog box. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Changing the Dialog Box ΓòÉΓòÉΓòÉ To change the properties of a dialog box or a single control, use the following functions of the Edit menu: o Select New Dialog to create another dialog box in the same resource file. Your existing dialog box will stay in memory. o Select Select Dialog to switch to another open dialog box. o Select Symbols to define symbols. Eight of the editing functions require that you first select the control to be edited. The selected control will appear in the drag window, surrounded by eight dots, one in each corner and one at the midpoint of each side. Selected Edit Menu Functions The following functions all require that a control must first be selected: o Select Cut to cut a control you would like to move or delete. o Select Copy to copy to the clipboard a control you would like to duplicate elsewhere in the same dialog or in another dialog. o Select Paste to place a control you have marked with Cut or Copy. o Select Clear to erase a control. o Select Duplicate to create another control in this dialog box identical with the selected control. o Select Styles to define the style of the selected control. o Select Presentation parameters to select color & font. o Select Size to text to adjust an entry field's size to the text inside. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Using the Options Menu ΓòÉΓòÉΓòÉ On the Options menu, a check mark next to each option shows whether it is selected (on) or not (off). To toggle your selection of options on and off, use the following functions of the Options menu: o Select Test mode to test the dialog. o Select Hex mode to toggle between hex and decimal display of ID Values of symbols. o Select Translate mode to toggle translate mode on and off. o Select Enable 2.0 styles to use controls and their styles which are specific to OS/2* 2.0, but not prior releases. If you are creating a dialog which will be used on computers running OS/2 version 1.3, for instance, you will want to toggle this option off. o Select Show status area to toggle display of the status area on and off. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Testing the Dialog Box ΓòÉΓòÉΓòÉ To test the dialog box, select Test Mode from the Options menu. The dialog box is displayed as it appears to the user from a program. In test mode, you can select controls, and their appearance changes in the same way as they do in an application. To return to work mode, click on Test Mode again to de-select it. If you want to make changes, you may edit the dialog box. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Ending an Edit Session ΓòÉΓòÉΓòÉ To end the edit session, select Close from the system pull-down menu. you see prompts for the file names of the files you want to save. If you want to edit the same file the next time you use the editor, select Open from the File menu. ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Dialog Templates ΓòÉΓòÉΓòÉ The Dialog Editor creates an ASCII text file that has the file-name extension .DLG. The compiled form of this file, created using the Resource Compiler, has the file-name extension .RES. The .DLG file contains a series of statements, collectively termed a dialog template, that define each dialog box and each control in each dialog box. The statement for each dialog box contains the data required to create it, namely its class, size, position, window text, and any other special information required for the window. Normally, the template consists of a dialog box window followed by the controls contained within it, as child windows. The DLGINCLUDE statement specifies the file name of the include file. The DLGTEMPLATE statement specifies the symbolic identifier of the dialog box (MYDIALOG), and loading and memory options. The actual dialog template is contained by the first BEGIN and last END statement. There is a CONTROL statement for each of the controls in the dialog box. The CONTROL statement is a general statement that is followed by parameters that further specify the control: o Text, where appropriate. For example, the text OK is defined for one of the pushbuttons. o Application-defined symbolic or integer identifiers for each control. Your application uses the identifier to track the responses from controls. For example, ID_NULL is the identifier of the text control. o The types and positions of the various controls. For example, the group box control is a control window of window class WC_STATIC. The Cancel and Help pushbuttons are of window class WC_BUTTON. o The appearance and operation of the dialog box and its controls are specified in detail by combinations of style parameters. For example, the check boxes have a class style of BS_CHECKBOX, and radio buttons have a class style of BS_RADIOBUTTON. You can also specify appropriate WS_* styles. If necessary, you can use a text editor to edit the .DLG file, for example, to fine-tune the dialog template produced by the dialog box editor. You can even use a text editor to produce your own .DLG file. The Dialog Editor uses the general CONTROL statement with window classes and control styles to define controls. You can use the CONTROL statement in the same way to define your controls, or you can use any of several predefined control statements that give you the same result. For example, the predefined control statement PUSHBUTTON gives you a WC_BUTTON class window with default styles of BS_PUSHBUTTON and WS_TABSTOP. A dialog template can be in either of the following: o A resource file, (generated from the .DLG or .RES file) o A block of memory that has the DLGTEMPLATE data structure, in which case you use WinCreateDlg (WCCRD) to create the dialog box from the template. The dialog template uses device-independent dialog units for the coordinate system that defines the layout of controls in the dialog box. A dialog unit is expressed in terms of the default standard character size, which can vary from device to device. You do not need to put code in your application to reformat the dialog box when displaying it on different devices. (Dialogs may need editing if a different system font is loaded.) A horizontal dialog unit is 0.25 of the standard character size. A vertical dialog unit is 0.125 of the standard character size. Dialog units are expressed as offsets from the origin (lower-left corner) of the dialog box. A dialog template is a general structure. It equally could be termed a window template, because you can use it to define any window in an application. If you prefer, use the statement WINDOWTEMPLATE instead of DLGTEMPLATE, because it is functionally identical. This could reduce the initialization phase of the application to registering the application window classes and calling WinLoadDlg (WCLD) to load the template. If you use the Dialog Editor to define a standard window, you will have to edit the resulting .DLG file, to ensure that you have a client window and the required parent-child relationships. You will also have to use WinLoadMenu (WCLM) in your application, to create an menu bar for the window, because you cannot create menus using the Dialog Editor. The .RES file is an object-format compiled version of the .DLG file, created when the Dialog Editor calls the Resource Compiler. The Dialog Editor uses the .RES file as input on any subsequent edit of the same dialog. This means that, if you use a text editor to fine-tune a .DLG file, and you want subsequently to re-edit the dialog using the Dialog Box Editor, you must first use the Resource Compiler to generate a new .RES file from the .DLG file. Your application can use either the .RES file output by the Dialog Editor, or a .RES file created from the .DLG file and the other resources. If your application uses the .DLG file, it must be included by the resource script file of your application. The rcinclude statement includes the .DLG file created by the Dialog Editor; for example: rcinclude dbe.dlg /* Includes .DLG file */ The corresponding .H file created by the Dialog Editor must also be included in the .RC file. To see how the rcinclude statement fits in with other resource definitions, and how to include the .H file, see RCINCLUDE Statement (in Resource Compiler documentation). Using OS/2*-defined control windows, OS/2 draws and operates the controls specified in the resource file for your application. Controls are windows and can be used within any other window. Related Topic Dialog Template Sample ΓòÉΓòÉΓòÉ <hidden> Dialog Editor - Sample Dialog Template File ΓòÉΓòÉΓòÉ The following dialog template is used for the dialog described in Adding Controls Example: DLGINCLUDE 1 "DBE.H" DLGTEMPLATE mydialog LOADONCALL MOVEABLE DISCARDABLE BEGIN DIALOG "Sample Dialog Box", mydialog, 11, 8, 170, 105, FS_NOBYTEALIGN | FS_DLGBORDER | WS_VISIBLE | WS_SAVEBITS, FCF_TITLEBAR BEGIN CONTROL "Student Level:", id_null, -1, 94, 63, 9, WC_STATIC, SS_TEXT | DT_LEFT | DT_TOP | WS_GROUP | WS_VISIBLE CONTROL "Elementary", 258, 7, 82, 62, 11, WC_BUTTON, BS_RADIOBUTTON | WS_GROUP | WS_TABSTOP | WS_VISIBLE CONTROL "Intermediate", 259, 7, 67, 73, 9, WC_BUTTON, BS_RADIOBUTTON | WS_VISIBLE CONTROL "Advanced", 260, 7, 51, 52, 13, WC_BUTTON, BS_RADIOBUTTON | WS_VISIBLE CONTROL "Media", 261, 87, 48, 75, 54, WC_STATIC, SS_GROUPBOX | WS_GROUP | WS_VISIBLE CONTROL "Text books", 262, 97, 83, 60, 10, WC_BUTTON, BS_CHECKBOX | WS_TABSTOP | WS_VISIBLE CONTROL "Video", 263, 97, 68, 46, 10, WC_BUTTON, BS_CHECKBOX | WS_VISIBLE CONTROL "CBT", 264, 97, 53, 32, 10, WC_BUTTON, BS_CHECKBOX | WS_VISIBLE CONTROL "OK", 265, 7, 20, 38, 12, WC_BUTTON, BS_PUSHBUTTON | WS_GROUP | WS_TABSTOP | WS_VISIBLE CONTROL "Cancel", 266, 61, 20, 38, 12, WC_BUTTON, BS_PUSHBUTTON | WS_TABSTOP | WS_VISIBLE CONTROL "Help", 267, 117, 20, 38, 12, WC_BUTTON, BS_PUSHBUTTON | WS_TABSTOP | WS_VISIBLE END END ΓòÉΓòÉΓòÉ 3. Font Editor ΓòÉΓòÉΓòÉ Select One: Introduction Using the Font Editor Defining Fonts Editing Character Width Font Resource Files ΓòÉΓòÉΓòÉ <hidden> Font Editor - Introduction ΓòÉΓòÉΓòÉ You can use the OS/2* Font Editor to design and save your own fonts for use in applications. A font is a set of alphanumeric characters, punctuation marks, and other symbols that share a common typeface design and line weight. An application loads a font from a dynamic-link library file (.DLL file). The Font Editor allows you to edit an enlarged version of each character in an editing window, using the mouse to switch the enlarged representation of pels to black or white. You can change a series of pels by dragging the mouse pointer through them while holding down the mouse button. An enlarged scale version of the character is shown in a viewing window to the right of the edit window. ΓòÉΓòÉΓòÉ <hidden> Using the Font Editor ΓòÉΓòÉΓòÉ To run the Font Editor, select Font Editor from the Development Tools group. Select one of the options in the File menu to open a new or existing font. The letter A appears in both the editing and viewing windows. The rest of the font appears in the character selection scroll box at the bottom of the Font Editor window. To edit any other character in the font, select it from the character selection scroll box. The character appears in the editing and viewing windows. Font Editing Functions Functions for defining fonts are found on the Header menu. Functions for editing character width are found on the Width and Shift menus. ΓòÉΓòÉΓòÉ <hidden> Font Editor - Defining Fonts ΓòÉΓòÉΓòÉ Use the Header menu to define the typestyle that you want to create: o Select General to specify spacing (fixed or proportional), type face style, line width, and type weight. o Select Naming to specify the identification details such as the type-face name. o Select Relations to specify the position of characters. o Select Sizes to specify the font character dimensions. o Select Definitions to change character spacing in a proportional font. ΓòÉΓòÉΓòÉ <hidden> Font Editor - Editing Character Width ΓòÉΓòÉΓòÉ The Width and Shift menus allow you to change the width of individual characters. The Width Menu Use the Width menu to alter the width of a single character. This menu is enabled only when you are editing a proportional space font. You can make a character wider or narrower by adding or deleting columns of pels from the right, the left, or both sides. You may also use the Set Character Increment option to set the width of a character. On-line help panels describe how to perform these functions. The Shift Menu Use the Shift menu to insert a one-pel-wide row or column into (or delete from) the character that you are editing. When you select shift, the pointer becomes a flat horizontal or vertical bar when inside the edit window. This enables you to position it exactly where you want the operation to take place. To cancel a shift you have selected before execution, select Cancel Choice. ΓòÉΓòÉΓòÉ <hidden> Font Editor - Font Resource Files ΓòÉΓòÉΓòÉ The Font Editor creates a file with a .FNT extension. The .FNT file is not referred to in the same resource file as other resources. Instead, it has its own resource file that contains a single-line statement that has a similar format to the ICON, POINTER, and BITMAP statements, for example: FONT 101 myfont.fnt /* Font */ The FONT keyword identifies the resource type. The resource type is followed by an integer identifier that is used by the application to identify the resource. The integer is used as a parameter to the WinCreateStdWindow (WICRTS) call. You cannot use a symbolic name for a font. The integer identifier can be followed by loading and memory options. Again, the example lets them default. The last part of the statement is the file name of the resource created by the Font Editor. A full path name must be given if it is not in the current directory. Producing a font file uses a process similar to binding resources to an .EXE file. You bind one or more .FNT files to a dummy .DLL, to produce a file containing the font or fonts. The final file should have the extension .FON. The .FON file created by the process is installed on the system and becomes a public font, a font that can be used by any application in the system. A font not installed on the system is called a private font. Before your application can use the font, your application must use GpiLoadFonts to load the .FON file. ΓòÉΓòÉΓòÉ 4. Icon Editor ΓòÉΓòÉΓòÉ Select One: Introduction Using Creating a Figure Editing Art Using Options Pen Shape/Size Preferences Hotspot Selecting Colors Editing Filling Areas Multiple Displays Multiple Sessions Command Line ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Introduction ΓòÉΓòÉΓòÉ The Icon Editor lets you create your own art (icons, pointers, and bit maps), and save them for use by applications. Icons, pointers, and bit maps produced by the Icon Editor are graphic symbols comprised of pels (also known as pixels) in any of the following display states: o Black o White o Color o Screen (background color) o Inverse screen (inverse of background color). An application can use an icon to represent a minimized standard window. For example, an application that lists telephone numbers could use a telephone icon when minimized. An application can also use icons as warning symbols in message boxes, for example, an exclamation mark or an upraised hand. An application can associate a pointer with the mouse or similar pointing device, so that the user can move the pointer around the screen, and select controls or text. A pointer could also be used to draw graphics on the screen, in an interactive graphics application. For example, a free-hand graphics drawing application could use a pencil shape to represent the pointer. ΓòÉΓòÉΓòÉ <hidden> Using the Icon Editor ΓòÉΓòÉΓòÉ To run the Icon Editor, select the Development Tools folder and then select Icon Editor. The Icon Editor display consists of three parts: the information panel, the palette window, and the editing window. The information panel at the top of the Icon Editor window displays the following information: o A picture of a two-button mouse, showing the colors currently selected for each button o An actual-size image of the current figure that you are editing o The status area, showing the following: Size (defined as 32 x 32 for icons and pointers; user-defined for bit maps) Pen location Pen size (from 1 x 1 to 9 x 9) Hotspot (for icons and pointers, but not bit maps) Figure type (icon, pointer, or bit map) Form name The palette window, in the lower right corner, displays the colors that are available for use during editing. The colors currently selected are marked with frames. The editing window is the largest part of your working area. Use the mouse or keyboard to move the pointer, clicking or dragging it, to paint the enlarged representation of pels with the selected color. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Creating a Figure ΓòÉΓòÉΓòÉ The Edit menu includes the functions used to select a an icon, pointer, or bit map for editing, and to save it after you are through. Selecting your icon, pointer, or bit map o To create a new icon, pointer, or bit map, select New from the File pull-down menu. The New Figure pop-up window appears, prompting you for further information. Select the figure type: Icon, Pointer, or Bit map. For a bit map you must specify the width and height in pels. If the bit map is larger than the screen, scroll bars will appear to allow you move around, to work on the off-screen portions of your bit map. Select Enter. You can also create new art by modifying or editing an existing art of the same type. o To edit existing art, select Open from the File pull-down menu. You will be prompted for a name. Note: Unless you have turned off Safe Prompting (under Setting Preferences on the Options menu), you will be prompted to save if you select Open or New while there is unsaved art on your screen. o If you started Iconedit from the prompt and specified multiple files, you can use the Next option on the File menu to select the next file. The Next option will be greyed out if you did not start from the command line and specify multiple files. Saving your icon, pointer, or bit map To save your art, select either of the following: o Select Save to save it under its current file name. If this is new art, you will be prompted for a name. o Select Save As to save the art under a different name. You will be prompted for a new name. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Editing Art ΓòÉΓòÉΓòÉ To edit your art, use the functions of the Edit menu. Select Undo to restore the art to the way it was before the most recent editing operation. Four of the editing functions require that you first mark the area to be edited, using Select or Select All. If you choose Select, the cursor changes to a rectangle. Hold the mouse button down to anchor one corner, and then drag the mouse. Release the button to anchor the opposite corner of the area you want to edit. If you choose Select All, the entire figure is selected. Selected Edit Menu Functions The following functions all require that an area must first be selected: o Select Fill to fill the selected area with the current palette color. For additional information, see Filling Areas With Color. o Select Cut to cut an area you would like to move or delete. o Select Copy to copy an area you would like to duplicate elsewhere in the same file or in another file. o Select Paste to place an area you have marked with Cut or Copy. Drag the outlined area which you have marked to the place you would like to paste it. o Select Clear to erase all drawing within an area you have selected, and leave transparent pels. When the completed used, the background color will be seen through these areas. If you have used Select All, this will clear your entire icon, pointer, or bit map. o Select Stretch Paste to paste the clipboard contents into your art, stretching and positioning to fit. o Select Flip Horizontal to flip the art on its horizontal axis, reversing bottom and top. o Select Flip Vertical to to flip the art on its vertical axis, reversing left and right. You can create a symmetrical drawing by copying one side of the art to the other side, and then flipping one of them. o Select Circle to inscribe a circle or ellipse within the selected area. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Using Options ΓòÉΓòÉΓòÉ The choices on the Options menu enable you to test your art and vary your editing environment. To change an option, select it on the Options menu. Test To test view the pointer or icon you are editing. The pointer or icon will be displayed, actual size, as the pointer until you toggle back by again selecting Test on the Options menu. Grid To superimpose a grid over the editing window. This can be useful when you want to draw a symmetrical figure. Each cell of the grid represents one pel in the figure. draw straight To temporarily restrict your drawing to drawing straight vertical and horizontal lines. Even if you deviate from the horizontal row, a horizontal line is produced when the mouse pointer is dragged across the editing window. Dragging the mouse up or down produces straight vertical lines. X background To make the transparent pels (where the background is visible) apparent when editing an icon or pointer. All screen or inverse screen colors will be shown with an X. This option does not apply to bit maps because they have no transparent pels. Changing Pen Shape See Changing Pen Shape and Size Changing Pen Size See Changing Pen Shape and Size Setting Preferences See Setting Preferences Defining a Hotspot See Defining a Hotspot ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Changing Pen Shape and Size ΓòÉΓòÉΓòÉ You can change the shape and size of the pen by using choices on the Options menu. Changing Pen Shape Before you select Pen Shape, you must first select the shape using the Select function on the Edit Menu. See Editing Art for information about Select. Then select Pen Shape on the Options menu. Changing Pen Size Select Pensize on the Options menu to specify how many pels the pointer paints at a time. You may select any of nine square pen sizes: 1 x 1 4 x 4 7 x 7 2 x 2 5 x 5 8 x 8 3 x 3 6 x 6 9 x 9 Shortcut: Select a pen size by pressing [Ctrl] and the size, such as [Ctrl]+6 for a 6 x 6 pen size. . ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Setting Preferences ΓòÉΓòÉΓòÉ To change your preferences, select Preferences on the Options menu. Then select any of the following: Safe Prompting To be warned before destructive operations such as file overwrites. Suppress Warnings To suppress display of informational messages. Save state on exit To save settings for your next session. Display Status Area To toggle on and off the picture of the mouse and art from the status area. Reset Options and Modes To deselect the following items: Select Hotspot Color Fill Find Color The palette will not be reset. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Defining a Hotspot ΓòÉΓòÉΓòÉ The Hotspot is the pel where where mouse input for an icon or pointer is directed. The default hotspot location is 16 x 16, the center of the icon or pointer. Bit maps do not have hotspots. Select Hotspot on the Options menu to designate this pel. The cursor changes shape, and the screen coordinates of the current hotspot are displayed in the information window. When you click on a new hotspot, the screen coordinates of the new hotspot are displayed. Select Hotspot again to return to editing. When an application uses WinQueryPointerPos (WMQPTP) to query the screen position of a pointer, the OS/2* operating system returns the coordinates of the pointer's hot spot. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Selecting Colors ΓòÉΓòÉΓòÉ Use the Palette to select a new drawing color, using the left or right mouse button. The currently selected color for the right mouse button is framed on the palette in red; the color for the left mouse button is framed in green. The currently selected colors for both mouse buttons are also displayed at the left side of the status area. Changing Palettes or Palette Colors To change palettes or palette colors, select the Palette menu. On the Palette menu, you have the following choices: o Select New to create a new palette. The default palette will appear for you to edit. o Select Open to open an existing palette. o Select Save to save your current palette. If it is a new palette, you will be prompted for a name. o Select Save As to save the palette under a different name. You will be prompted for a new name. o Select Edit Color to edit a color in your palette. o Select Swap colors to swap the colors of the left and right mouse buttons. A dialog will appear, asking whether you want to preserve these colors in your art. Unless you choose Preserve Figure, the colors in your art will be changed accordingly. o Select Set default palette to save the existing palette as your default palette. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Editing Palette Colors ΓòÉΓòÉΓòÉ You can change the colors that appear on your palette. To edit palette colors, follow these steps: 1. Select the color to be edited with the mouse. A frame appears around it on the palette. 2. Select Edit color on the Palette menu. Shortcuts: o Double click on the color to be edited. o To select a color that you have already used in your art, use Find color on the Tools menu. The Edit color window will appear. 3. You can change the way you define palette colors by checking Dynamic editing and Important and choosing between RGB and HSV terms. o Dynamic editing, when checked, will make your art change dynamically as you edit individual colors, so that you can see how the changes will affect your art. o Important, when checked, will require that the color be accurately rendered, without dithering. o Every color may be described numerically in either RGB or HSV terms. RGB As proportions of primary colors red, blue, and green HSV In terms of hue, saturation, and value To toggle between RGB and HSV, select the appropriate radio button. 4. Use the scrollbars to change RGB or HSV values, or change these numbers from the keyboard. 5. Select OK to save the edited color. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Filling Areas With Color ΓòÉΓòÉΓòÉ There are two different ways to fill an area with color: o To fill an irregularly-shaped area with the current palette color, select Color fill on the Tools menu. After you click on a specific pel, all adjoining areas that are the same color as that pel will be colored with the selected color. o To fill a previously-selected area with the current palette color, select Fill on the Edit menu. You must first select a area. See Editing Art for information about Select and Select All. Note: To select a color that you have already used in your art, use Find color on the Tools menu. A question-mark-arrow cursor will appear. Click on a specific pel of that color, and that color is selected. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Creating Icons for Specific Displays ΓòÉΓòÉΓòÉ Although the Icon Editor edits and saves a device-independent form of the icon, the Device menu enables you to create versions of the icon for specific display devices. The Device menu displays a choice of three functions: create a new device form, select an existing form, and delete a form. An independent form is automatically created when you create a new icon or pointer and all other forms are derived from it. If you select any of the other device forms listed in the menu, a new form is created for the specified device. The Custom option enables you to create an icon or pointer for any other device. Select List to view a list of all existing forms, including custom and standard forms. Any item on this list may be selected and edited or deleted. However, you must have at least one device-independent form. Select Add in the list dialog to add a new device form. Several icon bit maps may be saved in a single icon resource; when the icon is saved, all versions are saved with it in a format that includes a device resolution tag for each version. When the icon is loaded from a resource file, the display device resolution is matched against the device for which each device-dependent icon was intended. If a match is found, that icon is used. If no match is found, the application uses the device-independent icon, which always exists. Figure files may contain any of the following forms to support multiple devices: o Independent o CGA (2 colors) o EGA (16 colors) o VGA (16 colors) o 8514 (256 colors) o Custom Device-dependent icons are icons that are designed for a particular display resolution. An application can display icons or bit maps in dialog boxes or windows. The file name extension depends on the type of resource you are creating. The Icon Editor produces a file with any of the following extensions: .ICO for icons .PTR for pointers .BMP for bit maps The .ICO, .PTR, or .BMP files must be referred to in the resource script file for your application. The external files containing icons, pointers, and bit maps are all referenced in the resource script file by single-line statements that have a similar format. For example: ICON ID_MAINWND myprog.ico /* Icon */ POINTER ID_PTR mypoint.ptr /* Pointer */ BITMAP ID_BMP mybtmp.bmp /* bit map */ ICON, POINTER, and BITMAP keywords identify the resource type. The resource type is followed by a symbolic name or integer identifier that is used by your application to identify the resource. For example, with ICON, the ID_MAINWND identifier can be used by the application in the control data parameter of the WinCreateWindow (WICRT) call (or as a parameter to the WinCreateStdWindow (WICRTS) call) that creates the frame of your application's main window. The OS/2* operating system then associates the icon with the main window. The symbolic name or identifier can be followed by loading and memory options. The options are not used by the example, as it lets the options default. The last part of the statement is the file name and file type of the resource created by the Icon Editor. A fully qualified path name must be given if the file is not in the current directory. An icon that it used for a minimized application main window should have the same file name as the application's executable file. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Starting a Session ΓòÉΓòÉΓòÉ When a new text-window or full screen session is started, and the user has not explicitly supplied an icon file, the system looks for an .ICO file in the same subdirectory as the executable program, and uses that icon file instead of the default OS/2* or VIO icon. If CMD.EXE is to be run in the new session, the program name (for the purposes of looking for the icon file) will be the string that follows /K (or /C) in the argument string. Thus, for START "title" /C myfile the icon file used is MYFILE.ICO. If an error occurs while loading the icon file, the icon file is ignored and the default icon used. Note that, if an error occurs when loading an icon, the call returns an error. ΓòÉΓòÉΓòÉ <hidden> Icon Editor - Using a Command Line ΓòÉΓòÉΓòÉ If you start the Icon Editor from a command line, rather than from an icon, you have an additional option available. You can load more than one file at a time, by specifying them on the command line when entering the Icon Editor. For instance, the following command would load the two specified icons, a bit map, and a pointer: ICONEDIT marion.ico gurp.ico alex.bmp pamela.ptr If you started ICONEDIT from the command line and specified multiple files, you can use the Next option on the File Menu. to select the next file. This option is only available if you specified multiple files and started from the command line. ΓòÉΓòÉΓòÉ 5. EXEHDR ΓòÉΓòÉΓòÉ Select One: Introduction Help Syntax Options Output Header Listing Object Listing Output Example ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Introduction ΓòÉΓòÉΓòÉ The Executable File Header Utility (EXEHDR) displays and modifies the contents of an executable-file header. EXEHDR generates a listing showing the contents of the file header and information about each object or segment in the file. Options are provided that let you change values in the file header. Uses of EXEHDR include: o Determining whether a file is an application or a dynamic link library o Viewing and changing the attributes set by the module definition file o Viewing the number and size of code and data segments. You can use EXEHDR with DOS or OS/2* applications and dynamic-link libraries. You can run EXEHDR on OS/2 Version 1.3 files. In that case, EXEHDR utility will allow you to display and modify the contents of the file header and information about each segment in the file. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Syntax ΓòÉΓòÉΓòÉ EXEHDR [options] filename <options> Options used to modify EXEHDR output or change the file header <filename> One or more names of applications or dynamic-link library files Regardless of options, EXEHDR always creates a listing of the file header. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Help ΓòÉΓòÉΓòÉ To display EXEHDR help, type EXEHDR /? at the command prompt. The appropriate copyright statement appears along with a brief list of EXEHDR options. Usage: EXEHDR [options] filename... Valid options are: /? /HEAP:(0H - ffffH) /HELP /MAX:(0H - ffffH) /MIN:(0H - ffffH) /NEWFILES /NOLOGO /PMTYPE:(PM | VIO | NOVIO | WINDOWAPI | WINDOWCOMPAT | NOTWINDOWCOMPAT) /RESETERROR /STACK:(0H - ffffH) /VERBOSE ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Options ΓòÉΓòÉΓòÉ Usage Notes: o Option characters are not case sensitive: /R and /r are equivalent. o Options can be shortened to the fewest characters that uniquely identify them. The characters in brackets can be omitted: /N and /NOLOGO are equivalent. o Although use of the minimum one-letter abbreviations is allowed, if a future release has an additional option starting with the same letter, the one-letter option will no longer be usable. /? Display Help /HEA[P] Set Heap Allocation /HEL[P] Display Help /MA[X] Set Maximum Allocation /MI[N] Set Minimum Allocation /NE[WFILES] Enable long file name support /NO[LOGO] Suppress Sign-On Banner /P[MTYPE] Set Application Type /R[ESETERROR] Reset LINK386 Error /S[TACK] Set Stack Allocation /V[ERBOSE] Display in Verbose Mode Related Topic Formats Affected by Options ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Formats affected by Options ΓòÉΓòÉΓòÉ The EXEHDR options that can change executable files are MIN, MAX, STACK, PMTYPE, HEAP, RESETERROR, and NEWFILES. Executable headers are used by the operating system to determine characteristics of the executable file, such as stack size, entry point, number of objects (or segments), and so on. EXEHDR recognizes three different kinds of executable headers: DOS (generated by DOS linker), OS/2* OS/2 16-bit (generated by LINK), and OS/2 32-bit (generated by LINK386). An X in the following table indicates which option changes which executable header: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé ΓöéDOS ΓöéOS/2 16-bit ΓöéOS/2 32-bit Γöé Γöé Γöé Γöé(LINK) Γöé(LINK386) Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéHEAP Γöé ΓöéX ΓöéX Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéMAX ΓöéX Γöé Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéMIN ΓöéX Γöé Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéNEWFILES Γöé ΓöéX Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéPMTYPE Γöé ΓöéX ΓöéX Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéRESETERROR Γöé ΓöéX ΓöéX Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéSTACK ΓöéX ΓöéX Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ For compatibility purposes, executable files generated by either of the OS/2 link utilities include both a DOS header and an OS/2 header. For example, if you use /STACK on an executable generated by OS/2 LINK (16-bit), the DOS header and the OS/2 header will be changed. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /HEA[P] ΓòÉΓòÉΓòÉ Set Heap Allocation (/HEAP) Syntax: /HEA[P]:nnnn This option sets the size of the local heap and is applicable to OS/2* applications only. The field <nnnn> contains the local heap size in bytes. You can specify <nnnn> in decimal, octal, or hexadecimal radix using standard C language notation. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /HEL[P] and /? ΓòÉΓòÉΓòÉ Display Help (/HELP or /?) Syntax: /HEL[P] OR /? This option displays a brief summary of EXEHDR syntax. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /MA[X] ΓòÉΓòÉΓòÉ Set Maximum Allocation (/MAX) Syntax: /MA[X]:nnnn This option sets the maximum allocation of memory for the program. The field <nnnn> contains the maximum number of 16-byte paragraphs required to load and run the program. This value must be equal to or greater than the minimum allocation. Compare to Set Minimum Allocation (/MIN) The Maximum Allocation option is equivalent to the LINK386 /CP option. Refer to Set Max Allocation Space (/CP) (in LINK386 Help) You can specify <nnnn> in decimal, octal, or hexadecimal radix using standard C language notation. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /MI[N] ΓòÉΓòÉΓòÉ Set Minimum Allocation (/MIN) Syntax: /MI[N]:nnnn This option sets the minimum allocation of memory for the program. The field <nnnn> contains the minimum number of 16-byte paragraphs required to load and run the program. This value must be equal to or less than the maximum allocation. Compare to Set Maximum Allocation (/MAX) You can specify <nnnn> in decimal, octal, or hexadecimal radix using standard C language notation. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /NE[WFILES] ΓòÉΓòÉΓòÉ New Files (/NEWFILES) Syntax: /NE[WFILES] This option enables long file name support for OS/2 16-bit LINK files. OS/2 32-bit LINK386 files have long file name support. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /NO[LOGO] ΓòÉΓòÉΓòÉ Suppress Sign-On Banner (/NOLOGO) Syntax: /NO[LOGO] This option suppresses the sign-on banner displayed by EXEHDR when it starts. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /P[MTYPE] ΓòÉΓòÉΓòÉ Set Application Type (/PMTYPE) Syntax: /P[MTYPE]:type This option specifies the type of application. It pertains only to OS/2* applications. The /PMTYPE option in EXEHDR is equivalent to either the NAME Statement in the module-definition file or the NAME Application Type Option (/PM) in LINK386. A keyword in <type> is equivalent to a keyword in a NAME statement, as shown in the following list: Field Keyword Equiv. Keyword PM WINDOWAPI VIO WINDOWCOMPAT NOVIO NOTWINDOWCOMPAT The NAME statement keyword is also accepted. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /R[ESETERROR] ΓòÉΓòÉΓòÉ Reset LINK386 Error (/RESETERROR) Syntax: /R[ESETERROR] This option clears an error flag stored in OS/2* and applications. The error flag is set by LINK386 when the link has unresolved external references or duplicate symbol definitions (any LINK386 error messages starting with L2xxx). OS/2 does not load the application if the error flag is set. This option allows you to attempt to run a program with LINK386 errors and is useful during application development. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /S[TACK] ΓòÉΓòÉΓòÉ Set Stack Allocation (/STACK) Syntax: /S[TACK]:nnnn This option sets the size of the stack. The field <nnnn> contains the stack size in bytes. This option is equivalent to the Control Stack Size Option (/ST) (in LINK386 Help) You can specify <nnnn> in decimal, octal, or hexadecimal radix using standard C language notation. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - /V[ERBOSE] ΓòÉΓòÉΓòÉ Display in Verbose Mode (/VERBOSE) Syntax: /V[ERBOSE] This option displays the executable-file header in verbose mode. Related Topics EXEHDR Output Example Ouput Using Verbose Option ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Output ΓòÉΓòÉΓòÉ EXEHDR lists the current contents of the file header and information about each object (or segment) in the file. To redirect this output to a printer or disk file, use the operating system redirection operator. The output is in two parts: a Header Listing giving the contents of the file header; and an Object (or Segment) Listing giving attributes of all objects (or segments) in the file. If the /VERBOSE option is specified, additional output is generated. Related Topic Output Example ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Header Listing ΓòÉΓòÉΓòÉ The header listing is comprised of the following fields: <Module> Name of Application p.This field lists the name of the application as specified in the NAME statement of the module-definition file. If no module definition was used to create the executable file, this field displays the name assumed by default. If a module definition was used to create the file, but the LIBRARY statement appeared instead of the NAME statement (thus specifying a dynamic-link library), the name of the library is given and EXEHDR uses the word "Library" instead of "Module" to identify the field. <Description> Description of Application This field gives the contents, if any, of the DESCRIPTION statement of the module-definition file used to create the file being examined. <Data> Type of Automatic Data Object This field indicates the type of automatic data segment in a program: SHARED, NONSHARED, or NONE. This type can be specified in a module-definition file. The defaults are NONSHARED for applications and SHARED for dynamic-link libraries. <Initial CS:IP> Program Starting Address This field gives the program starting address (if an application is being examined) or address of the initialization routine (if a dynamic-link library is being examined). <Initial SS:SP> Initial Stack Pointer This field gives the value of the initial stack pointer. <Extra Stack Allocation> Additional stack allocation This field gives the value of the extra stack location. <DGROUP> Automatic-Data-Object Number ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Object or Segment Listing ΓòÉΓòÉΓòÉ The object listing is comprised of the following fields: no. Object index number, starting with 1, in decimal type Identification of the object as a code or data object A code object is comprised of segments with class name ending in CODE. All other objects are data objects. address Location, within the file, of the contents of the object (in hexadecimal) file Size of the object (in bytes), as contained in the file (in hexadecimal) mem Size of the object (in bytes), as it is stored in memory (in hexadecimal) If the value of this field is greater than the value of <file>, the operating system pads the additional space with zero values at load time. flags Object attributes If the /VERBOSE option is not used, only nondefault attributes are listed. Attributes are given in the form specified in the module-definition file. ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Output Example ΓòÉΓòÉΓòÉ The following output is generated by EXEHDR for the executable file LINK386.EXE: Module: LINK386 Description: Operating System/2 32-bit LX Linker Data: NONSHARED Initial CS:IP: seg 2 offset 6c78 Initial SS:SP: seg 4 offset 0000 Extra stack allocation: 4000 bytes DGROUP: seg 4 no. type address file mem flags 1 CODE 00006000 0f7d6 0f7d7 2 CODE 00015a00 08e40 08e40 3 DATA 0001ea00 02865 02865 4 DATA 00021400 02337 08bd0 ΓòÉΓòÉΓòÉ <hidden> EXEHDR - Verbose Output ΓòÉΓòÉΓòÉ When you specify the /VERBOSE option, EXEHDR generates additional output: o DOS-specific header information. All OS/2* executable files have a DOS header, whether bound or not. If the program is not bound, the DOS portion typically consists of a stub that simply terminates the program. o OS/2-specific header information. The object-table display in verbose mode is described below. o File addresses and lengths of the various tables in the executable file. For each table, the following is generated: - Name of the table - Address of the table within the file - Length of the table in hexadecimal radix - Length of the table in decimal radix o Object table with complete attributes, not just the nondefault attributes. The /VERBOSE option displays two additional attributes: - The RELOCS attribute is displayed for each object that has address relocations. Relocations occur in each object that references objects in other objects or makes dynamic-link references. - The ITERATED attribute is displayed for each object that has iterated data. Iterated data consist of a special code that packs repeated bytes. o Run-time relocations and fixups. o All exported entry points. ΓòÉΓòÉΓòÉ 6. FWDSTAMP ΓòÉΓòÉΓòÉ Select one: Introduction Uses Starting FWDSTAMP Example ΓòÉΓòÉΓòÉ <hidden> FWDSTAMP - Introduction ΓòÉΓòÉΓòÉ FWDSTAMP adds entry points, called forwarders, to a dynamic link library file (.DLL). Forwarders point to API functions or other exported code or data. They contain an import reference so that the final target address of the forwarded entry is contained in a different module. A forwarder might be called an imported export. When a file has a fix-up to a forwarded entry point, the loader resolves that fix-up to the address of the entry point that the forwarder imports by traversing the chain of forwarders until the end of the chain (a nonforwarded export) is reached. All forwarders are implicitly exported. The imported entry point that a forwarder refers to may itself be another forwarder. The loader will process a chain of forwarders until a nonforwarder entry point is encountered. There is no run-time cost to forwarders; however, there is a slight load-time cost as the loader resolves forwarder chains with their final addresses. ΓòÉΓòÉΓòÉ <hidden> FWDSTAMP - Using Forwarders ΓòÉΓòÉΓòÉ You use forwarders to combine several DLLs into one without having to relink old applications. For example, if MOUCALLS and VIOCALLS were combined into a single DLL called NEWLIB.DLL, then MOUCALLS and VIOCALLS could be replaced with special DLLs containing forwarders to NEWLIB.DLL. Important Notes o FWDSTAMP parses only the IMPORTS and EXPORTS section of the module definition file. FWDSTAMP does not verify the syntax of the other sections. o When exported names already exist in the input file, their attributes are kept, such as resident or nonresident names table, and ordinal numbers. Any new conflicting attributes are ignored. o If there is no exported name, FWDSTAMP adds the one defined by the EXPORTS statement in the module definition file. ΓòÉΓòÉΓòÉ <hidden> FWDSTAMP - Starting FWDSTAMP ΓòÉΓòÉΓòÉ You can start FWDSTAMP and specify all input from the command line. An example of the syntax follows: FWDSTAMP [options] infile deffile outfile [options] Specifies one of the following: /? Displays FWDSTAMP help panel. /V Increases the level of information FWDSTAMP should output. infile Specifies the name of the dynamic link library file that LINK386 created. Use the file-name extension of DLL. deffile Specifies the name of the module definition file (.DEF) that contains the forwarders. (See Example) outfile Specifies the name of the .DLL file that will contain the added forwarders. ΓòÉΓòÉΓòÉ <hidden> FWDSTAMP - Example ΓòÉΓòÉΓòÉ Forwarders are specified in the module definition file so that an exported name, which is also imported, is a forwarder. For example: IMPORTS VIOMODEWAIT=NEWLIB.123 EXPORTS VIOMODEWAIT @ 25 In the example, a forwarder entry point for VIOMODEWAIT is created and contains an import reference to NEWLIB.123. ΓòÉΓòÉΓòÉ 7. IMPLIB ΓòÉΓòÉΓòÉ Select One: Introduction Running IMPLIB Help Syntax Options Error Messages ΓòÉΓòÉΓòÉ <hidden> IMPLIB -Introduction ΓòÉΓòÉΓòÉ IMPLIB creates import libraries used to link dynamic-link libraries with applications. Import libraries are created by IMPLIB and used to link dynamic-link libraries with applications. What Are Import Libraries? Import libraries are similar in some respects to standard libraries: o You specify import libraries and standard libraries in the same command line field of LINK386 or OS/2 16-bit LINK. o Both kinds of libraries resolve external references at link time. However, import libraries differ from standard libraries in that they contain no executable code. Rather, they identify the dynamic-link libraries where the executable code can be found at run time. Why Use Import Libraries? Creating import libraries is an extra step. Nevertheless, import libraries are recommended for use with all dynamic-link libraries for two reasons: o IMPLIB automates much of the program creation process for you. To use IMPLIB, supply it with the .DEF file you already created for the dynamic-link library. Without an import library, you must create a second .DEF file that explicitly defines all needed functions in the dynamic-link library. o Import libraries make it easier for one person to write a library and another to write the application. Much of the linking process (linking the .DLL file and creating the import library) can be done by the author of the dynamic-link library. The import library and associated .DLL file can then be given as a unit to the person linking the application - that person need not worry about creating a .DEF file. ΓòÉΓòÉΓòÉ <hidden> Running IMPLIB ΓòÉΓòÉΓòÉ The following options can be used with IMPLIB: <options> The option that modifies the IMPLIB output. See IMPLIB Options <implibname> Import library created <deffile> One or more module definition files that export routines in the dynamic-link library <dllfile> One or more dynamic-link libraries with exported routines. Hints o You can specify any number of either module definition files or dynamic-link libraries. o By using the _export keyword in C, you can declare functions that are exported from the dynamic-link library. ΓòÉΓòÉΓòÉ <hidden> IMPLIB - Help ΓòÉΓòÉΓòÉ To display IMPLIB help, type the following at the command prompt: IMPLIB /? The appropriate copyright statement is displayed along with a list of IMPLIB options. Usage: IMPLIB [options] implibname {deffile... | dllfile...} Valid options are: /? /HELP /IGNORECASE /NOIGNORECASE /NOLOGO ΓòÉΓòÉΓòÉ <hidden> IMPLIB - Syntax ΓòÉΓòÉΓòÉ IMPLIB [options] implibname {deffile...| dllfile...} Syntax Example The following command creates the import library named MYLIB.LIB from the module definition file MYLIB.DEF. IMPLIB MYLIB.LIB MYLIB.DEF ΓòÉΓòÉΓòÉ <hidden> IMPLIB - Options ΓòÉΓòÉΓòÉ Usage Notes: o Option characters are not case sensitive: /H and /h are equivalent. o Options can be shortened to the fewest characters that uniquely identify them. The characters in brackets can be omitted: /NOL and /NOLOGO are equivalent. o Although use of the minimum one-letter abbreviations is allowed, if a future release has an additional option starting with the same letter, the one-letter option will no longer be usable. The following options may be used with IMPLIB: /? Displays a short summary of IMPLIB syntax. /H[ELP] Displays a short summary of IMPLIB syntax. /I[GNORECASE] Turns case sensitivity off. This is the default. /I[GNORECASE] Turns case sensitivity on. By default, case sensitivity is off. /NOL[OGO] Suppresses the sign-on banner when IMPLIB starts. ΓòÉΓòÉΓòÉ <hidden> IMPLIB - Error Messages ΓòÉΓòÉΓòÉ There are two types of IMPLIB error messages: o Fatal errors cause IMPLIB to stop running. Message numbers IM1600 through IM1606 report these problems. o Nonfatal errors indicate problems in the library file. IMPLIB produces the library file and sets the error bit in the header for the OS/2 environment. This means that the library file cannot be run from OS/2. Message numbers IM2600 through IM2604 report these problems. IM1600 error while writing to output file - name Explanation: There was not enough disk space available to create the target library. Action: Delete or move files to make space on the disk and restart IMPLIB. IM1601 out of memory - heap name heap exhausted Explanation: There was not enough memory available to run IMPLIB. Action: Reduce the number of programs presently running in your system and restart IMPLIB. IM1602 error in the module definitions file Explanation: There was an error in the module definition (.DEF) file. Action: Correct the symbol shown in the message, at the line number given. Restart IMPLIB. IM1603 name : cannot create file reason Explanation: IMPLIB was unable to open or create the target library specified. Action: Check the file name and available space. Restart IMPLIB. IM1604 name : cannot open file - reason Explanation: IMPLIB was unable to open one of the specified input module definition (.DEF) files. Action: Check the file name. Restart IMPLIB. IM1605 too many nested include files in module definition file Explanation: The .DEF file exceeded a nesting level. Action: Combine some nestings into one .DEF file and try again. IM1606 missing or bad include file name Explanation: IMPLIB could not find a file included by .DEF file. Action: Make sure the file exists and can be located and that any path is specified correctly. Try again. IM2600 line number is too long; truncated to length characters Explanation: You have tried to export more than 8192 names. Action: Retry with fewer names, creating an additional executable module if necessary. IM2601 symbol multiply defined Explanation: An export name was repeated within or across the module definition (.DEF) files. Action: Eliminate duplicate definitions of the export name. IM2602 unexpected end of name table in DLL Explanation: IMPLIB encountered an error when reading the module names table or procedures names table. Action: The 9per.DLL file is corrupted. Check to make sure that the DLL was generated by OS/2 LINK or LINK386. IM2603 name : invalid .DLL file Explanation: IMPLIB could not parse the DLL properly. Action: The .DLL file is corrupted. Check to make sure that the DLL was generated by OS/2 LINK or LINK386. IM2604 unrecognized option 'option'; option ignored Explanation: You specified an incorrect option. Action: Specify a correct IMPLIB option. ΓòÉΓòÉΓòÉ 8. KwikINF ΓòÉΓòÉΓòÉ Select One: Introduction Configuring KwikINF Automatic Text Retrieval BOOKSHELF Online Documents Index Files for Rapid Search Enabling Online Documents Using KwikINF Command Line KwikINF Activation Key Sequence Full Screen Sessions Default Volume to Search Activation Behavior Search from the KwikINF Window Search String Entry Field VOLUME TO SEARCH List Box KwikINF Keys Help ΓòÉΓòÉΓòÉ <hidden> Introduction ΓòÉΓòÉΓòÉ KwikINF provides you with a quick and convenient method of accessing information in online documents stored in the OS/2* 2.x BOOKSHELF from anywhere on the desktop, with the exception of DOS or WIN-OS/2 sessions. When KwikINF has been started, you can open a dialog with KwikINF by pressing a user-selectable hot key. Until you configure KwikINF, your KwikINF hot key is ALT+Q. The KwikINF window includes a Configure push button. This opens another dialog with KwikINF: the Configure KwikINF window. The KwikINF window also allows you to initiate searches for text strings in online documents of choice. ΓòÉΓòÉΓòÉ <hidden> Automatic Text Retrieval ΓòÉΓòÉΓòÉ The KwikINF window includes a Search String entry field. You can specify the text string you want KwikINF to search for. Or, under certain conditions, this entry field automatically contains the word located under the cursor when you press your KwikINF hot key. This text retrieval feature is available from OS/2 full-screen and Presentation Manager (PM) multi-line entry (MLE) fields. This feature is also available from PM AVIO and VIO windows. Communication Manager's 3270 emulator is a common example of a PM AVIO window. An OS/2 Window is a VIO window. This means that if, for example, you open an OS/2 Window and start an OS/2 text-based application, KwikINF will automatically retrieve the word under the cursor when you press your KwikINF hot key. This automatic text-retrieval feature is not available from graphic-text PM windows. ΓòÉΓòÉΓòÉ <hidden> BOOKSHELF Online Documents ΓòÉΓòÉΓòÉ The KwikINF window includes a Volume to Search list box of all online documents stored in the OS/2 BOOKSHELF subdirectories. KwikINF initiates searches for information in any online document in this list. The BOOKSHELF is an environment variable, set in CONFIG.SYS, that contains a list of subdirectories containing online documents created as viewable .INF files with the Information Presentation Facility (IPF). The BOOKSHELF environment variable is set as follows: SET BOOKSHELF=<subdirectory>;...;<subdirectory>; Online documents for OS/2 (for example, the Command Reference) are stored in the \OS2\BOOK subdirectory of the drive on which OS/2 is installed. Online documents for the OS/2 Toolkit (for example, the Programming References) are stored in the \TOOLKTxx\BOOK subdirectory of the drive specified during installation of the online programming information. As an example, after installation of OS/2 and the OS/2 2.1 Toolkit, the BOOKSHELF environment variable is set as follows: SET BOOKSHELF=C:\OS2\BOOK;C:\TOOLKT21\BOOK; The online document where KwikINF looks for the Search String is selected from the Volume to Search list box by KwikINF or by you. KwikINF selects the Volume to Search by looking for the text string that has a matching entry in the KwikINF index file or, if there is no matching entry in the index file, in the Default Volume you have selected in the Configure KwikINF window. ΓòÉΓòÉΓòÉ <hidden> Index Files for Rapid Search ΓòÉΓòÉΓòÉ The KwikINF index file provides a rapid-search mechanism for locating specific kinds of information in online documents in the BOOKSHELF. The KwikINF index file consists of one or more concatenated files stored in the BOOKSHELF and defined by the HELPNDX variable in CONFIG.SYS as shown in the following example: SET HELPNDX=EPMKWHLP.NDX where EPMKWHLP.NDX is the KwikINF index file for the OS/2 Toolkit. As an example, the following excerpt from the KwikINF index file for the OS/2 Toolkit: EXTENSIONS: * DESCRIPTION: IBM Developer's Toolkit for OS/2 2.1 (IPF*, view ipfc20.inf ~) (WinCreateWindow, view pmwin.inf ~) is used by KwikINF to quickly locate Search String entries with the prefix IPF in the IPF-viewable file IPFC20.INF. and to quickly locate the specific Search String entry WinCreateWindow in the IPF-viewable file PMWIN.INF. The first token in a rapid-search string is a specific text string (for example, WinCreateWindow) or prefix wildcard (for example, IPF*). The second token is the name of the IPF file viewer (VIEW.EXE). The third and fourth tokens are parameters for VIEW.EXE: the name of the .INF file that contains the online document and the text-string you want VIEW.EXE to locate within the online document. The ~ character tells KwikINF to use the first token in the rapid-search string as the text-string to locate within the online document. ΓòÉΓòÉΓòÉ <hidden> Enabling Online Documents ΓòÉΓòÉΓòÉ You can enable any online document for KwikINF by: 1. Creating the online document as a viewable .INF file using the Information Presentation Facility (IPF). 2. Adding the name of the subdirectory where it is stored to the PATH statement in CONFIG.SYS. 3. Appending the name of the subdirectory where it is stored to the BOOKSHELF in CONFIG.SYS. 4. Creating an index file to support the KwikINF rapid-search mechanism, storing it in the BOOKSHELF, and adding it to the HELPNDX variable in CONFIG.SYS. For example, you can enable your online document MYDOC stored in MYSUBDIR subdirectory for KwikINF by: 1. Compiling the tagged source for MYDOC with the IPF compiler by entering: IPFC MYDOC /INF 2. Modifying the PATH statement in CONFIG.SYS as follows: SET PATH=...;C:\MYSUBDIR; 3. Modifying the BOOKSHELF statement in CONFIG.SYS as follows: SET BOOKSHELF=...;C:\MYSUBDIR; 4. Creating MYINDEX file in MYSUBDIR as shown below: /* C style comments and blank lines are acceptable */ /* specific file extensions may be specified here */ EXTENSIONS: * /* a title may be placed here */ DESCRIPTION: Any custom KwikINF index file /* rapid-search strings */ (thisfunction, view mydoc.inf ~) (my*, view mydoc.inf ~) 5. Modifying the HELPNDX variable in CONFIG.SYS as follows: SET HELPNDX=EPMKWHLP.NDX+MYINDEX For more information on creating an IPF-viewable online document, see the IPF Reference in the Toolkit Information folder. ΓòÉΓòÉΓòÉ <hidden> Using KwikINF ΓòÉΓòÉΓòÉ KwikINF is installed as a program object in the OS/2 2.1 Toolkit Information folder. You start KwikINF by double-clicking on the KwikINF object or by entering KwikINF from the command line of an OS/2 Window. You can start KwikINF automatically when you start OS/2 by placing a shadow of the KwikINF object in the Startup folder in the OS/2 System folder on the desktop. You shadow an object by pressing CTRL + SHIFT while dragging the object. KwikINF installs a PM system hook to monitor keystrokes in PM sessions and OS/2 character device monitors to monitor keystrokes in OS/2 full-screen sessions. KwikINF will install only one copy of the hook and monitors, even if you attempt to re-start KwikINF. When KwikINF has been started, you can initiate searches for text strings in online documents of choice by pressing a user-selectable hot key. Note: You cannot initiate searches for text strings in online documents from DOS or WIN-OS/2 sessions. Until you configure KwikINF, your KwikINF hot key is ALT+Q. You configure KwikINF by pressing your KwikINF hot key and then pressing the Configure push button to open the Configure KwikINF window. Note: When you start KwikINF by double-clicking on the KwikINF object in the Toolkit Information folder, a message box tells you what hot key opens the KwikINF window. This technique can also be used to determine what your current KwikINF hot key is, after KwikINF has been started. How you initiate a search for information in online documents is dependent on where you are on the desktop when you press the KwikINF hot key: o From an OS/2 full-screen session, a PM VIO or AVIO window, or PM MLE: position the cursor on the string you want to search for and press the KwikINF hot key. KwikINF retrieves the word at the cursor. If you have configured KwikINF to display the KwikINF window when the KwikINF hot key is pressed, KwikINF automatically places the retrieved word in the Search String entry field of the KwikINF window. When you press the Search push button or Enter, KwikINF displays the information. If you have configured KwikINF to bypass the KwikINF window when the KwikINF hot key is pressed, KwikINF automatically displays the information. If no word is under the cursor, the previous Search String is used. If no previous Search String exists, KwikINF displays the Contents of the Default volume to search. o From a graphic-text PM window: press the KwikINF hot key, then type the string you want to search for in the Search String entry field of the KwikINF window. The KwikINF text-retrieval feature is not available from graphic-text PM windows. The online document where KwikINF looks for the text string is selected from the Volume to Search list box by KwikINF or by you. To open the online document to the panel that contains the information, press the Search push button or press Enter. ΓòÉΓòÉΓòÉ <hidden> KwikINF From the Command Line ΓòÉΓòÉΓòÉ You can start, terminate, and configure KwikINF from the command line in an OS/2 Window by entering: KwikINF [no options] [/C] [/T] [/?] where: no options starts KwikINF. After entering this command, the default KwikINF hot key (ALT + Q) is enabled. /T terminates KwikINF and disables the KwikINF hot key. /C opens the Configure KwikINF window. Use this window to select another KwikINF hot key, to select a default online document from the BOOKSHELF to search, and to select the activation behavior of the KwikINF window. /? displays the following information. Usage: KwikINF [Option] Option Description /C Configure KwikINF /T Terminate KwikINF /? This short help list ΓòÉΓòÉΓòÉ <hidden> Configuring KwikINF ΓòÉΓòÉΓòÉ You configure KwikINF through the Configure KwikINF window. KwikINF displays this window when you press the Configure push button on the KwikINF window or when you enter the following from the command line of an OS/2 Window: KwikINF /C The Configure KwikINF window allows you to: o Select another KwikINF hot key. o Specify the number of OS/2. full-screen sessions enabled for KwikINF o Specify the name of the default online document KwikINF searches. o Select the activation behavior of the KwikINF window. Use the push buttons on the Configure KwikINF window as follows: o Press OK to enable your configuration choices. o Press Cancel to cancel your configuration choices. This closes the Configure KwikINF window. o Press Help to get general help for the current window. ΓòÉΓòÉΓòÉ <hidden> Activation Key Sequence ΓòÉΓòÉΓòÉ The Activation Key Sequence provides a selectable list of KwikINF hot keys. To access the list, single-click on the down arrow. Select the KwikINF hot key of your choice from the following list: CTRL + A CTRL + H CTRL + Q ALT + A ALT + Q (this is the default hot key) The KwikINF hot key initiates searches for information in online documents from anywhere on the desktop, with the exception of DOS or WIN-OS/2 sessions. ΓòÉΓòÉΓòÉ <hidden> Full Screen Sessions ΓòÉΓòÉΓòÉ Use the Number of Fullscreen Sessions to Monitor spin button to specify the number of OS/2 full-screen sessions enabled for KwikINF. KwikINF is implemented as a PM system hook to monitor keystrokes in PM sessions and as OS/2 character device monitors to monitor keystrokes in OS/2 full-screen sessions. For OS/2 full-screen sessions, KwikINF will monitor only the number of sessions specified here. ΓòÉΓòÉΓòÉ <hidden> Default Volume to Search ΓòÉΓòÉΓòÉ Use the Default Volume to Search single selection list box to specify which online document in the BOOKSHELF you want KwikINF to search by default. KwikINF looks for the Search String in this online document, when there is no matching entry in the KwikINF index file. Select the online document, then select the OK push button to activate the selection. ΓòÉΓòÉΓòÉ <hidden> Activation Behavior ΓòÉΓòÉΓòÉ Use the Activation Behavior radio buttons to select the behavior of the KwikINF window. The KwikINF window can be displayed or bypassed when the user presses the KwikINF hot key after KwikINF has been installed. o Select the Display KwikINF Window radio button to tell KwikINF that you always want the KwikINF window to be displayed when you press the KwikINF hot key to initiate searches for information. This is the default behavior of the KwikINF window. When the you press the KwikINF hot key, you can initiate a search for the text string that may be automatically displayed in the Search String entry field or for the text string that you enter into this field. You can also specify which online document in the BOOKSHELF KwikINF searches for the text string. o Select the Bypass KwikINF Window radio button to tell KwikINF that you do not want the KwikINF window to be displayed when you press the KwikINF hot key to initiate searches for information. This is typically used when working under conditions where the KwikINF automatic text-retrieval feature is available. When you press the KwikINF hot key, KwikINF automatically looks for the text string under the cursor in the online document that has a matching entry in the KwikINF index file or, if there is no matching entry in the index file, in the Default volume selected from the Configure KwikINF window. You configure KwikINF by pressing the Configure push button in the KwikINF window. To configure KwikINF when this window is bypassed, press SHIFT + your KwikINF hotkey to display the Configure KwikINF window. ΓòÉΓòÉΓòÉ <hidden> Searching Using the KwikINF Window ΓòÉΓòÉΓòÉ If you have configured KwikINF to display the KwikINF window (this is the default condition), the KwikINF window is displayed when you press your KwikINF hot key. The KwikINF window allows you to search for a text string in an online document in the OS/2 BOOKSHELF. The text string is typed by you in the Search String entry field or is automatically retrieved by KwikINF, under certain conditions, from under the cursor when you press your KwikINF hot key. The online document that KwikINF searches for the text string is selected from the Volume to Search list box by KwikINF or by you. KwikINF selects the Volume to Search by looking for the text string that has a matching entry in the KwikINF index file or, if there is no matching entry in the index file, in the Default Volume you have selected in the Configure KwikINF window. Or you can override KwikINF's selection of the Volume to Search by making your own selection from the list box. To initiate the search for the text string in the online document, press the Search push button or press Enter. If the search is successful, KwikINF opens the online document to the online panel that contains the information and displays a window with a title bar that matches the search string. If the search is not successful, you can search any online document for the information by following this procedure: o Clear the Search String entry field. o Select an online document from the Volume to Search list box. The Contents window of the online document appears. o Select Services from the menu bar. o Select Searchfrom the Services pull down menu. The Search help window appears. o Type the text string, then select the All libraries radio button. o Select the Search push button or press Enter. Use the push buttons on the KwikINF window as follows: o Press Search to initiate the search for the text string in the Search String entry field in the selected online document. o Press Cancel to cancel the request to search for the text string and to close the KwikINF window. o Press Configure to display the Configure KwikINF window. o Press Help to get general help for the current window. ΓòÉΓòÉΓòÉ <hidden> Search String Entry Field ΓòÉΓòÉΓòÉ KwikINF searches for the text string in this entry field in the selected online document in the OS/2 BOOKSHELF. Under certain conditions, KwikINF automatically retrieves the word under the cursor when you press your KwikINF hot key. Letters, numbers, underscores, and the pound sign are retrievable by KwikINF. Blank spaces and other special characters are used as delimiters and are not retrievable by KwikINF. You may also type any text string you want into this field. All characters are valid in the entry field to allow for special search criteria. ΓòÉΓòÉΓòÉ <hidden> VOLUME TO SEARCH List Box ΓòÉΓòÉΓòÉ The KwikINF window includes a list box of all online documents stored in the OS/2 BOOKSHELF subdirectories. KwikINF initiates searches for information in any online document in this list. The online document where KwikINF looks for the Search String is selected from the Volume to Search list box by KwikINF or by you. KwikINF selects the Volume to Search by looking for the text string that has a matching entry in the KwikINF index file or, if there is no matching entry in the index file, in the Default Volume you have selected in the Configure KwikINF window. Or you can override KwikINF's selection of the Volume to Search by making your own selection from the list box. You can also open and display the Contents of an online document by double-clicking on an entry in this list box. ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ Trademark of the IBM Corporation. ΓòÉΓòÉΓòÉ <hidden> KwikINF Keys Help ΓòÉΓòÉΓòÉ Use your KwikINF hot key (ALT+Q or the hot key you select from the Configure KwikINF window) to display the KwikINF window. You can also use your KwikINF hot key to initiate a search for a text string automatically, when you configure KwikINF to bypass the KwikINF window. To re-configure KwikINF, when you have configured KwikINF to bypass the KwikINF window, press SHIFT + your KwikINF hot key. To determine what your KwikINF hot key is, double-click on the KwikINF program object in the OS/2 Toolkit Information folder. ΓòÉΓòÉΓòÉ 9. LINK386 ΓòÉΓòÉΓòÉ Introduction Starting LINK386 Syntax Default Libraries Filenames Module Definition Files Basics Example Rules Statements Options Using Recommendations Numeric Arguments Environment Variable OS/2* Considerations Output Error Messages ΓòÉΓòÉΓòÉ <hidden> LINK386 - Introduction ΓòÉΓòÉΓòÉ LINK386 is used to combine object files and standard library files into a single file: an executable file, a dynamic-link library, or a device driver. The output file from LINK386 is not constrained to specific memory addresses. Thus, the operating system can load and execute this file at any convenient address. LINK386 Input LINK386 uses the following files as input: o One or more object files that are linked with any optional library files to form the executable file. Object files usually have a .OBJ extension. LINK386 accepts object files compiled or assembled for 80386 or 80486 microprocessor. Object files must be in the Object Module Format (OMF), which is based on the Intel(R) 8086 OMF. o One or more library files. The library files contain object modules that are linked to the object files to form the executable file. Library files usually have a .LIB extension. Library files are used to resolve external references in your object files. o A module definition file. The module definition file provides information to LINK386 about the executable file or dynamic link library file it is creating. The module definition file usually has a .DEF extension. LINK386 Output LINK386 can produce executable files of up to 16 megabytes. LINK386 can also produce dynamic-link libraries (.DLL) and device drivers (.DRV), in addition to executable files (.EXE). For additional information, see Output Files. LINK386 displays all of its output messages on the standard output device. LINK386 Features LINK386 creates the executable file and map file in the current directory unless you enter an explicit path. LINK386 looks in several locations for object, library, and module-definition files. See Where LINK386 Looks for Files. File names are not case sensitive; for example, abc.exe and ABC.EXE refer to the same file. If you enter a file name without an extension, LINK386 adds a default extension that depends on the type of file expected. If you leave a field blank (but define the field with a comma), LINK386 uses a default for the field. If you end the LINK386 command with a semicolon (;), LINK386 uses defaults for all remaining fields. If you do not give all file names or do not end the command line with a semicolon, LINK386 prompts you for the omitted files. ΓòÉΓòÉΓòÉ <hidden> Starting LINK386 ΓòÉΓòÉΓòÉ Some commands and applications call LINK386 for you, or you can run LINK386 by typing LINK386 at the operating-system prompt. Supply input to LINK386 by any of three methods: o Enter the input directly on the command line o Respond to prompts generated by LINK386. o Put your input in a response file, and enter the file name on the command line. You can press Ctrl+C at any time to interrupt LINK386 and return to the operating system. If LINK386 runs out of memory, it creates a temporary file. To display LINK386 help, type LINK386 /? at the prompt. A copyright statement appears along with a list of valid LINK386 options. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Syntax ΓòÉΓòÉΓòÉ LINK386 [options] objfiles [,exefile, mapfile, libraries, deffile] OR LINK386 @responsefile SYNTAX DEFINITIONS The LINK386 command line includes the following fields: <options> Options modifying actions of LINK386. Options can appear anywhere on the command line except immediately after the commas used to separate fields. See LINK386 Options and Using LINK386 Options. <objfiles> Object files to be linked. Separate multiple file names by plus (+) or space characters. At least one name must be entered. Library files can also be entered. See Entering Library Files as Object Files. <exefile> Output of file. LINK386 produces either an executable file, a dynamic-link library, or a device driver. <mapfile> Map file created that lists modules in <exefile>. Use the /M option to include public symbols in this file. Enter NUL if you do not want a map file. See Include Public Symbols (/M). <libraries> Standard or import (not dynamic-link) libraries to be used in resolving external references. Separate multiple file names by plus (+) or space characters. Some libraries are searched by default. You can also specify a path to a directory -- LINK386 searches all libraries in this directory. See Linking with an Import Library, Default Libraries, and Specifying Library Directories. <deffile> Module definition file. SYNTAX EXAMPLES The following command links the object files FUN.OBJ, TEXT.OBJ, TABLE.OBJ, and CARE.OBJ. LINK386 searches for unresolved external references in the library file XLIB.LIB and in the default libraries. By default, the executable file is named FUN.EXE. LINK386 also produces a map file, FUNLIST.MAP. LINK386 FUN+TEXT+TABLE+CARE, ,FUNLIST, XLIB.LIB; The following command produces a map file named FUN.MAP because a comma appears as a placeholder for <mapfile>. LINK386 FUN,,; The next pair of command lines do not produce a map file because commas do not appear as placeholders for <mapfile>. LINK386 FUN,; LINK386 FUN; The following command links the files MAIN.OBJ, GETDATA.OBJ, and PRINTIT.OBJ into an executable file named MAIN.EXE. A map file named MAIN.MAP is also produced. LINK386 MAIN+GETDATA+PRINTIT, , MAIN; The following command links GETDATA.OBJ and PRINTIT.OBJ into an OS/2* dynamic-link library. MODDEF.DEF must contain a LIBRARY statement to produce the dynamic-link library. LINK386 GETDATA+PRINTIT,GETDATA.DLL, , MODDEF ΓòÉΓòÉΓòÉ <hidden> LINK386 - Object Files ΓòÉΓòÉΓòÉ LINK386 accepts object files compiled or assembled for the 80386 or 80486 microprocessor. LINK386 also accepts standard library files. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Output Files ΓòÉΓòÉΓòÉ LINK386 Can Produce Three Types of Output Files o Executable (.EXE) files that run under OS/2* version 2.0 protected mode LINK386 produces an executable file whenever you specify a module-definition file containing a NAME statement. The module definition file should not have a LIBRARY, VIRTUAL DEVICE, or PHYSICAL DEVICE statement; otherwise, a dynamic-link library or device driver is produced, as described below. o Dynamic-link library (.DLL) files A dynamic-link library is produced whenever you specify a module-definition file containing a LIBRARY statement. o Device driver (.DRV) files A virtual or physical device driver is produced whenever you specify a module-definition file containing the VIRTUAL DEVICE or PHYSICAL DEVICE statements. Related Topics OS/2 Considerations Error Messages ΓòÉΓòÉΓòÉ <hidden> LINK386 - Prompts ΓòÉΓòÉΓòÉ LINK386 prompts you if any fields have not been entered on the command line or in a response file. For each prompt, simply enter the same input that you would enter on the command line and press Enter. Object Modules [.OBJ]: <objfiles> Run File [basename.EXE]: <exefile> List File [NUL.MAP]: <mapfile> Libraries [.LIB]: <libraries> Definitions File [NUL.DEF]: <deffile> Special Features o To extend input to a new line, type a plus sign (+) as the last character on the current line. When the same prompt appears on a new line, you can continue. Do not, however, split a file name across lines. o To select the default response to a prompt, press Enter. The next prompt appears. o To select default responses to the current prompt and all remaining prompts, enter a semicolon (;). Note that at least one object file must be entered. o You can specify options anywhere on any response line, except before a comma at the end of a line of characters. If you want to specify more than one option, either group them at the end of a response, or specify them at the end of several responses. Each option must begin with a slash (/). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Response Files ΓòÉΓòÉΓòÉ A response file is a text file used to provide input to LINK386. To use response file input for LINK386, type LINK386 @responsefile The @ symbol tells LINK386 that filename starts the linker. If the file is not in the working directory, you must specify the path. The field <responsefile> specifies the name of a file containing the same input that would be entered on the command line or entered in response to LINK386 prompts. In this file, each response should appear on a separate line or be separated from other responses by a comma. To operate LINK386 using a response file, you must first create a file that contains the responses you want LINK386 to process. You can give the file any name, and create it with any text editor. Special Features: o You can begin using a response file at any point on the LINK386 command line or at any LINK386 prompt. The response file should contain responses to all remaining fields or prompts. o If the file does not contain responses for all the prompts, LINK386 displays the appropriate prompt and waits for you to supply a response. End the response file with a semicolon. You can use special characters in the response file the same way you would use them in responses entered at the keyboard. o You can use special characters in the response file the same way you would use them in responses entered at the keyboard. For example, you can extend input to a new line by using the plus sign (+) and choose default responses for all remaining prompts by using a semicolon (;). o LINK386 displays prompts and the entries from the response file on the screen. If the entry in the response file is not acceptable, LINK386 pauses and waits for you to enter an acceptable response. The /BA option disables the prompt. o Options can appear anywhere in the response file. Related Topic Response File Example ΓòÉΓòÉΓòÉ <hidden> LINK386 - Response File Example ΓòÉΓòÉΓòÉ FUN TEXT TABLE CARE /CO /MAP FUNLIST GRAF.LIB If the text file above were named FUN.LNK, the following command would use this file as a response file: LINK386 @FUN.LNK This would cause LINK386 to do the following: o Link the four object modules FUN, TEXT, TABLE, and CARE into an executable file named FUN.EXE o Generate the map file FUNLIST.MAP o Generate Debugging information o Include public symbols and addresses in the map file o Link any needed routines from the library file GRAF.LIB The response file in the following example instructs LINK386 to generate an executable file called FUN.EXE, and four object modules, FUN, SUN, RUN, and GAMES. If you specify the file name, FUNLIST, LINK386 will generate a map file named FUNLIST.MAP. Adding the /MAP option will cause LINK386 to include the public symbols of the application in the map file. fun+sun+run+game /map fun.exe funlist ; ΓòÉΓòÉΓòÉ <hidden> LINK386 - Temporary File ΓòÉΓòÉΓòÉ If LINK386 runs out of memory, it creates a temporary disk file. This file is deleted when LINK386 finishes. The location of the temporary file varies: o If a temporary directory is defined by the TMP environment variable, LINK386 stores the temporary file there. o If the TMP environment variable is undefined or the temporary directory doesn't exist, LINK386 stores the temporary file in the current working directory. When LINK386 creates a temporary file, you see the message: Temporary file tempfile has been created. Do not change diskette in drive letter. <tempfile> Name of temporary file <letter> Disk drive identifier where temporary file is stored (does not appear if drive is fixed) After this message appears, do not remove the disk from the drive specified by <letter> until the link session ends. If the disk is removed, the operation of LINK386 is unpredictable; and you may see the following message: Unexpected end-of-file on scratch file If this happens, run LINK386 again. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Default Libraries ΓòÉΓòÉΓòÉ Most compilers embed the names of needed libraries (called default libraries) in object files. LINK386 searches these libraries. Because of this, you need to explicitly enter library names only in the following cases: o You want to use additional libraries. o You are using a library not in the current directory and not in a directory specified by the LIB environment variable. See Where LINK386 Looks for Files. o You want to use a library other than the one specified in the object file. Explicitly entered libraries are always searched before default libraries. If an external reference is resolved by more than one library, the order of libraries on the command line determines which library is used. To ignore default libraries use the /NOD option But be careful - most compilers expect their object files to be linked with default libraries. Related Topics Where LINK386 Looks for Files Specifying Library Directories Entering Library Files as Object Files Library Search Example ΓòÉΓòÉΓòÉ <hidden> LINK386 - Entering Library Files as Object Files ΓòÉΓòÉΓòÉ You can enter library files in the <objfiles> field. Be sure to include the .LIB file name extension; otherwise, LINK386 assumes a .OBJ extension. With libraries entered in the <objfiles> field, LINK386 adds every module in the library to your output file. With libraries entered in the <libraries> field, LINK386 adds only those required to resolve external references. The effect of entering a library this way is the same as if you had entered all of the library's module names into the <objfiles>field. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Specifying Library Directories ΓòÉΓòÉΓòÉ LINK386 searches additional locations for libraries using the drive name or path specification in the <libraries> field on the command line. You can specify up to 32 additional paths. If you give more than 32 paths, LINK386 ignores the additional paths without displaying an error message. ΓòÉΓòÉΓòÉ <hidden> Where LINK386 Looks for Files ΓòÉΓòÉΓòÉ When searching for an object, library, or module definition file, LINK386 looks in the following locations in this order: 1. The directory specified for the file if a path specification is included. Default libraries do not include path specifications. 2. The current directory. 3. Any directories entered on the command line. 4. Any directories given by the LIB environment variable. If LINK386 cannot locate a file, it prompts you to enter the location. The /BA option disables these prompts. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Library Search Example ΓòÉΓòÉΓòÉ LINK386 Object Modules [.OBJ]: FUN TEXT TABLE CARE Run File [FUN.EXE]: List File [NUL.MAP]: Libraries [.LIB]: C:\TESTLIB\ NEWLIBV3 Definitions File [NUL.DEF]: This example links four object modules to create an executable file named FUN.EXE. LINK386 searches NEWLIBV3.LIB before searching the default libraries to resolve references. To locate NEWLIBV3.LIB and the default libraries, LINK386 searches the following locations in this order: 1. The current directory 2. The C:\TESTLIB\ directory 3. The locations given by the LIB environment variable Related Topics Specifying Library Directories Where LINK386 Looks for Files ΓòÉΓòÉΓòÉ <hidden> LINK386 - Filename Defaults ΓòÉΓòÉΓòÉ If you do not enter a file name, LINK386 assumes a default: <options> No options <objfiles> None (This field is required.) <exefile> The base name of the first file in <objfiles> with the .EXE extension added <mapfile> The base name in <exefile> with the .MAP extension added <libraries> No libraries <deffile> No module definition file Related Topic Filename Extension Defaults ΓòÉΓòÉΓòÉ <hidden> LINK386 - Default Filename Extensions ΓòÉΓòÉΓòÉ If you do not enter an extension, LINK386 uses a default extension, depending on the type of file. Object .OBJ Executable .EXE Map .MAP Standard Library .LIB Dynamic-Link Library .DLL Module Definition .DEF Device Driver .DRV Overriding Default Extensions Any time you explicitly enter an extension, it overrides the default extension. To specify a file name without an extension, just enter a period (.) after the file name. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Options ΓòÉΓòÉΓòÉ The following is a summary of LINK386 options: /? Display Help /A[LIGNMENT] Align /BAS[E] Base /BAT[CH] Run in Batch Mode /C[ODEVIEW] Prepare for Debugging /DE[BUG] Prepare for Debugging /DO[SSEG] Order Segments /E[XEPACK] Exepack /F[ARCALLTRANSLATION] Optimize Far Calls /H[ELP] Display Help /I[NFORMATION] Display Process Information /L[INENUMBERS] Include Line Numbers /M[AP] List Public Symbols /NOD[EFAULTLIBRARYSEARCH] Ignore Default Libraries /NOE[XTDICTIONARY] Ignore Extended Dictionary /NOF[ARCALLTRANSLATION] Disable Far Optimization /NOI[GNORECASE] Preserve Case Sensitivity /NOL[OGO] Disable Sign-On Banner /NON[ULLSDOSSEG] Order Segments without NULLs /NOP[ACKCODE] Disable Code-Segment Packing /PACKC[PACKCODE] Pack Contiguous Code /PACKD[ATA] Pack Contiguous Data /PAU[SE] Pause during Linking /PM[TYPE] Name Application Type /RU[NFROMVDM] Execute From Dos Command Line /SE[GMENTS] Set Max Number of Segments /ST[ACK] Control Stack Size /W[ARNFIXUP] Warn Fixup Options Not Supported Under LINK386 /O[VERLAYINTERRUPT] /CP[ARMAXALLOC] /PADC[ODE] /DS[ALLOCATE] /PADD[ATA] /Q[UICKLIB] /HI[GH] /T[INY] /INC[REMENTAL] /NOG[ROUPALIGN] Specifying LINK386 Options You can specify options anywhere on the response line, except before a comma at the end of a line of characters. If you want to specify more than one option, either group them at the end of a response, or specify them at the end of several responses. Each option must begin with a forward slash (/). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Using LINK386 Options ΓòÉΓòÉΓòÉ 1. Options always begin with the slash character (/). 2. Options are not case sensitive. For example, /de and /DE are equivalent. 3. You can specify options in either the short or long form. The short form is the shortest sequence of characters that uniquely identifies the option. The individual description of each option lists both forms with the optional part enclosed in brackets. For example, /BA[TCH] indicates that either /BA or /BATCH can be used. 4. Some linker options take numeric arguments. You can enter numbers in decimal, octal, or hexadecimal radix using standard C-language syntax. 5. You can also specify options in the LINK386 environment variable. 6. Although use of the minimum one-letter abbreviations is allowed, if a future release has an additional option starting with the same letter, the one-letter option will no longer be usable. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Recommendations ΓòÉΓòÉΓòÉ It is recommended that the ALIGN, BASE, and EXEPACK options be used when linking all executables. This will compress them in size and improve their performance. Use /ALIGN:4 for 32-bit applications and /ALIGN:16 for 16-bit applications. If you use BASE with .EXE files, the /BASE:0x10000 option must be used. Any other value will produce a warning. For .DLL files, use /BASE:0x12000000 (or a lesser value), remembering to provide a separate value for each .DLL. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Entering Numeric Arguments ΓòÉΓòÉΓòÉ Some LINK386 options and module statements take numeric arguments. LINK386 uses C-language syntax allowing you to specify numbers in any of the following forms: o Any number not prefixed with 0 or 0x is a decimal number. For example, 1234 is a decimal number. o Any number prefixed with 0 (but not 0x) is an octal number. For example, 01234 is an octal number. o Any number prefixed with 0x is a hexadecimal number. For example, 0x1234 is a hexadecimal number. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Environment Variable ΓòÉΓòÉΓòÉ You can use the LINK386 environment variable to cause certain options to be used each time you link. LINK386 checks the environment variable for options if the variable exists. LINK386 expects to find options listed in the variable exactly as you would type them on the command line. It does not accept other kinds of arguments; file names in the environment variable cause the following error message: unrecognized option Each time you link, you can specify other options in addition to the ones specified in the LINK386 environment variable. If you type an option both on the command line and in the environment variable, the effect is the same as if the option were given once. Note: A command line option overrides the effect of any environment-variable option that it conflicts with. For example, the command line option /SE:512 cancels the effect of the environment-variable option /SE:256. The only way to prevent an option in the environment variable from being used is to reset the environment variable itself. Related Topics LINK386 Environment Variable Example /SE /NOF ΓòÉΓòÉΓòÉ <hidden> LINK386 Environment Variable Example ΓòÉΓòÉΓòÉ <SET LINK386=/NOI /SE:256 /CO <LINK386 TEST; <LINK386 /NOD /CO PROG; In the example above, the file TEST.OBJ is linked with the options /NOI, /SE:256, and /CO. The file PROG.OBJ is then linked with the option /NOD - in addition to /NOI, /SE:256, and /CO. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Alignment (/A) ΓòÉΓòÉΓòÉ Syntax: /A[LIGNMENT]:n This option directs LINK386 to set the alignment factor in the executable file to the number given, which must be a power of 2, from 2 to 32 768. The default alignment is 512 bytes. Trailing zeroes are truncated to reduce the amount of data stored in a file. Each page starts at a location that is a multiple of n bytes from the beginning of the file. For example, /A:16 would start pages at multiples of 16 bytes. Since pages on OS/2* are 4096 bytes in length, it does not make sense to use a value greater than 4096 since this will just waste disk space. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Run in Batch Mode (/B) ΓòÉΓòÉΓòÉ Syntax: /BAT[CH] By default, LINK386 prompts you for a new path name whenever it cannot find an object file or library it was directed to use. This option disables such prompting. Instead, LINK386 generates an error or warning message, as appropriate, and leaves the external reference unresolved. The /B option also disables the display of the sign-on banner and the display of input from response files. This option is primarily used when LINK386 is called from a batch file or NMAKE description file. Note: This option does not affect prompts for command line input. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Prepare for Debugging (/C) ΓòÉΓòÉΓòÉ Syntax: /C[ODEVIEW] The /C option is used to prepare for debugging with the CodeView** debugger. This option works exactly like the /DE option. The /C option is used to prepare for debugging with CodeView. With this option, LINK386 imbeds symbolic data and line number information in the executable output file. You can run this executable file outside Debug; the debugging information in the file is ignored. However, to reduce executable file size, use this option only for debugging. Then you can link a separate version without the /C option after the program is debugged. ΓòÉΓòÉΓòÉ <hidden> LINK386 - /BASE (//BAS) ΓòÉΓòÉΓòÉ Syntax: BASE:n Where n is a value rounded up to the nearest multiple of 64K Indicates that each object of the module has a preferred load address starting with object 1 at this address, object 2 at the next available multiple of 64K, and so on. Internal relocation records are then applied using this addressing scheme. If the module's objects can be loaded beginning at this preferred address, then no load-time internal relocation records need be applied. If the module's objects cannot be loaded beginning at this preferred address, then the internal relocation records that have been retained in the file data will be applied. EXE files may specify a base address, but it must be 64K. If it isn't, a warning will be issued and a base address of 64K will be used anyway. This option provides the same support as the BASE module definition file statement. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Prepare for Debugging (/DE) ΓòÉΓòÉΓòÉ Syntax: /DE[BUG] The /DE option is used to prepare for debugging with any debugger. With this option, LINK386 embeds symbolic data and line number information in the executable output file. You can run this executable file outside Debug; the debugging information in the file is ignored. However, to reduce executable file size, use this option only for debugging. Then you can link a separate version without the /DE option after the program is debugged. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Order Segments (/DO) ΓòÉΓòÉΓòÉ Syntax: /DO[SSEG] This option is automatically enabled by a special object module record in many language libraries. If you are linking to one of these libraries, you need not specify this option. The /DO option is also enabled by assembly modules that use the Macro Assembler directive .DOSSEG. This option forces segments to be ordered as follows (first to last): 1. All code segments 2. Far data segments 3. Near data (DGROUP) segments, in the following order: a. Any segments of class BEGDATA (this class name is reserved) b. Any segments not of class BEGDATA, BSS, or STACK c. Segments of class BSS d. Segments of class STACK In addition, the /DO option causes LINK386 to do the following: o Initialize two special variables: _edata = DGROUP : BSS _end = DGROUP : STACK The variables _edata and _end have special meanings for certain compilers; avoid using these names in your programs. Assembly-language programs can refer to these variables, but should not change them. o Insert 16 null bytes at the beginning of the _TEXT segment (if this segment is defined). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Exepack (/E) ΓòÉΓòÉΓòÉ Syntax: /E[XEPACK] EXEPACK causes pages of data in the file to be compressed. The OS/2* Applications Loader will automatically decompress these pages when the program is run. Related Topic /NON ΓòÉΓòÉΓòÉ <hidden> LINK386 - Optimize Far Calls (/F) ΓòÉΓòÉΓòÉ Syntax: /F[ARCALLTRANSLATION] This option causes LINK386 to optimize far-call instructions made from one segment to a target address in the same segment. LINK386 replaces calling sequences such as CALL FAR function with the following: PUSH CS CALL NEAR function NOP The new calling sequence is significantly faster when running in protected mode. Also, a load-time relocation is eliminated, which decreases program file size and speeds program loading. In general, the greatest benefit occurs if you use the /PACKC option in addition to the /F option. The /F option has no effect on programs that make only near calls. Note: There is a small risk involved with using the /F option. LINK386 may mistakenly interpret a byte of immediate data in a code segment as a far call if it has to have the far-call opcode (0x9A). Related Topics /NOF ΓòÉΓòÉΓòÉ <hidden> LINK386 - Display Help (/H or /?) ΓòÉΓòÉΓòÉ Syntax: /H[ELP] OR /? These options display a list of valid LINK386 options. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Display Process Information (/I) ΓòÉΓòÉΓòÉ Syntax: /I[NFORMATION] This option causes LINK386 to display information about the linking process, including the phase of linking and the names of the object files being linked. Use this option to determine the locations of the object files being linked and the order in which they are linked. The output from this option is sent to standard output. Related Topics Example of /I Output ΓòÉΓòÉΓòÉ <hidden> LINK386 - Include Line Numbers (/L) ΓòÉΓòÉΓòÉ Syntax: /L[INENUMBERS] This option includes source file line numbers and associated addresses in the map file. In addition, you must give LINK386 an object file (or files) with line number information. You can use the /Zd option with most compilers to include line numbers in the object file. If you give LINK386 an object file without line number information, the /L option has no effect. The /L option forces LINK386 to create a map file even if you did not explicitly tell LINK386 to create a map file. By default, the file is given the same base name as the executable file, plus the extension .MAP. You can override the default name by explicitly specifying a map file name. ΓòÉΓòÉΓòÉ <hidden> LINK386 - List Public Symbols (/M) ΓòÉΓòÉΓòÉ Syntax: /M[AP][:full] This option lists in the map file all public (global) symbols defined in the object files. With this option, the map file contains a list of all the symbols sorted by name, and a list of all the symbols sorted by address. If you don't use this option, the map file contains only a list of segments. With this option, LINK386 creates a map file by default. If you explicitly enter a map file name of NUL, then no map file is created, and this option has no effect. The Map option can be specified as /M:full to produce a comprehensive map showing the composition of each segment. Related Topics Example of /M output ΓòÉΓòÉΓòÉ <hidden> LINK386 - Ignore Default Libraries (/NOD) ΓòÉΓòÉΓòÉ Syntax: /NOD[EFAULTLIBRARYSEARCH] [:filename] This option tells LINK386 to ignore default libraries when resolving external references. If you specify an object file in <filename>, LINK386 ignores only the default libraries in <filename>. In general, high-level-language programs do not work correctly without standard libraries. Thus, if you use the /NOD option, you should explicitly specify the name of a standard library in the <libraries> field of the command line. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Ignore Extended Dictionary (/NOE) ΓòÉΓòÉΓòÉ Syntax: /NOE[XTDICTIONARY] This option prevents LINK386 from searching the extended dictionary, an internal list of symbol locations included with libraries generated with the old LIB utility's /NOE option. Normally, LINK386 uses the extended dictionary to speed up library searches; thus, using /NOE slows LINK386. This option should be used when a library symbol is redefined. You need to use this option when LINK386 issues error L2044. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Disable Far Optimization (/NOF) ΓòÉΓòÉΓòÉ Syntax: /NOF[ARCALLTRANSLATION] Far-call optimization is off by default. If the LINK386 environment variable or another command (such as ICC) has turned it on, you can use /NOF to turn it off again. Related Topics LINK386 Environment Variable Optimize Far Calls (/F) ΓòÉΓòÉΓòÉ <hidden> LINK386 - Preserve Case Sensitivity (/NOI) ΓòÉΓòÉΓòÉ Syntax: /NOI[GNORECASE] This option turns case sensitivity on; that is, LINK386 treats ABC, abc, and Abc as unique names. By default, case sensitivity is off. This option can be used when you link programs written in case-sensitive languages such as C. ΓòÉΓòÉΓòÉ <hidden> Disable Sign-On Banner (/NOL) ΓòÉΓòÉΓòÉ Syntax: /NOL[OGO] This option disables the sign-on banner displayed when LINK386 starts. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Order Segments without NULLs (/NON) ΓòÉΓòÉΓòÉ Syntax: /NON[ULLSDOSSEG] This option arranges segments in a special order. The /NON option is equivalent to the Order Segments Option (/DO) except that /NON does NOT insert 16 null bytes at the beginning of the _TEXT segment (if this segment is defined). The /NON option overrides the /DO option when both are used. Therefore, you can use /NON to override the /DO comment record commonly found in standard libraries. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Disable Code-Segment Packing (/NOP) ΓòÉΓòÉΓòÉ Syntax: /NOP[ACKCODE] This option turns code segment packing off. By default, code segment packing is on. Related Topics Pack Contiguous Code (/PACKC) ΓòÉΓòÉΓòÉ <hidden> LINK386 - Pack Contiguous Code (/PACKC) ΓòÉΓòÉΓòÉ Syntax: /PACKC[ODE]:number This option groups neighboring code segments. Neighboring code segments are assigned the same segment address, and offsets to each routine are adjusted upward as required. This option is on by default and is used only when you wish to override an environment variable that has turned code packing off. See LINK386 Environment Variable and Disable Code-Segment Packing (/NOP). The <number> field specifies the maximum size of a code segment grouped by /PACKC. If you do not use the /PACKC option or if you omit <number>, maximum size defaults to 65,530. LINK386 stops adding segments to a group as soon as it cannot add another segment without exceeding <number>. At this point, LINK386 forms a new segment. See Entering Numeric Arguments Code packing generally produces slightly faster and more compact code. Use the /F option to provide the maximum opportunity for packing. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Pack Contiguous Data (/PACKD) ΓòÉΓòÉΓòÉ Syntax: /PACKD[ATA] [:number] This option groups neighboring data segments. It functions like the code packing option (/PACKC) except that it packs data segments. The <number> field specifies the maximum size of a data segment grouped by /PACKD; if you omit <number>, the maximum size defaults to 65,536. LINK386 stops adding segments to a group as soon as it cannot add another segment without exceeding <number>. At this point, LINK386 forms a new group. See Entering Numeric Arguments. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Pause during Linking (/PAU) ΓòÉΓòÉΓòÉ Syntax: /PAU[SE] This option makes LINK386 pause before writing the output file to disk. The pause allows you to swap disks. With this option, LINK386 displays the following message before it creates the output file: About to generate .EXE file Change diskette in drive letter and press Enter LINK386 writes the output file when you press Enter. Be sure not to remove a disk containing the map file or the temporary file. If the disk you need to swap contains either of these files, press CTRL+C to terminate the LINK386 session, rearrange your files, and link again. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Name Application Type (/PM) ΓòÉΓòÉΓòÉ Syntax: /PM[TYPE]:type This option specifies the type of application being generated. Using the /PM option is equivalent to including a NAME statement in the module definition file. A keyword in <type> is equivalent to a keyword in a NAME statement as shown in the following list: PM WINDOWAPI VIO WINDOWCOMPAT NOVIO NOTWINDOWCOMPAT ΓòÉΓòÉΓòÉ <hidden> LINK386 - Execute from DOS Command Line (/RU) ΓòÉΓòÉΓòÉ Syntax: /RU[NFROMVDM]: This option allows the program to be executed from a DOS command line, if possible. This option causes LINK386 to insert an alternate DOS stub into the program. The DOS stub is executed if a protect mode program is executed from a DOS command line. The default DOS stub simply prints an error message and returns to the DOS command line. The alternate DOS stub will attempt to start the program in protect mode. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Set Maximum Number of Segments (/SE) ΓòÉΓòÉΓòÉ Syntax: /SE[GMENTS]:number This option sets the number of logical segments a program can have. You can set <number> to any value in the range 1 to 3,072. See Entering Numeric Arguments. For each logical segment, LINK386 must allocate space to keep track of segment information. By using a relatively low segment limit as a default (128), LINK386 is able to link faster and allocate less storage space. When you set the segment limit higher than 128, LINK386 allocates more space for segment information. This option allows you to raise the segment limit for programs with a large number of segments. For programs with fewer than 128 segments, you can keep the storage requirements of LINK386 at the lowest level possible by setting the segment <number> field to reflect the actual number of segments in the program. If the number of segments allocated is too high for the amount of memory LINK386 has available to it, you see the error message segment limit too high. To specify a number of segments that fits in the amount of memory available, set the segment lower and relink. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Control Stack Size (/ST) ΓòÉΓòÉΓòÉ Syntax: /ST[ACK] :number This option controls the stack size (in bytes) of your program. You can specify any positive value for <number>. See Entering Numeric Arguments. If your program generates a stack-overflow message, you can increase the size of the stack. In contrast, if your program uses the stack very little, you may save some space by decreasing the stack size. Note: You can also use the EXEHDR utility to change the stack size of an existing executable file. Related Topics STACKSIZE Statement ΓòÉΓòÉΓòÉ <hidden> LINK386 - Warning of Fix-ups (/W) ΓòÉΓòÉΓòÉ Syntax: /W[ARNFIXUP] This option directs LINK386 to issue a warning for each segment-relative fix-up of location-type offset when the segment is contained within a group, but not at the beginning. LINK386 includes the displacement of the segment from the group in determining the final value of the fix-up. ΓòÉΓòÉΓòÉ <hidden> LINK386 - /INF and /M Output Example ΓòÉΓòÉΓòÉ The following is a sample of LINK386 output when /INF and /M options are specified: **** PASS ONE **** TEST.OBJ(test.for) **** LIBRARY SEARCH **** LLIBFOR7.LIB(wr) LLIBFOR7.LIB(fmtout) LLIBFOR7.LIB(ldout) Γöé Γöé Γöé **** ASSIGN ADDRESSES **** 1 segment "TEST_TEXT" length 122H bytes 2 segment "_DATA" length 912H bytes 3 segment "CONST" length 12H bytes Γöé Γöé Γöé **** PASS TWO **** TEST.OBJ(test.for) LLIBFOR7.LIB(wr) LLIBFOR7.LIB(fmtout) LLIBFOR7.LIB(ldout) Γöé Γöé Γöé **** WRITING EXECUTABLE **** ΓòÉΓòÉΓòÉ <hidden> LINK386 - OS/2 Considerations ΓòÉΓòÉΓòÉ In most respects, linking a program for OS/2* is similar to linking a program for DOS. The principal difference is that most programs created for DOS run as stand-alone applications, whereas programs for OS/2 generally call one or more dynamic-link libraries. See What Is a Dynamic-Link Library? and Advantages of Dynamic Linking. Import and Export Definitions Each dynamic-link library (.DLL file) defines export definitions that tell OS/2 what functions the library has. Functions not exported can only be called from within the library. Each export definition specifies a function name. Conversely, each executable program (.EXE file) defines import definitions that tell OS/2 which dynamic-link functions the program needs and where they can be found. Otherwise, OS/2 would not know which dynamic-link libraries to load when the program is run. Each import definition specifies a function name and the .DLL file where the function resides. Methods of OS/2 Linking There are two methods of OS/2 Linking: o Linking without an Import Library o Linking with an Import Library Linking with an import library requires more steps but has certain advantages. Related Topics What Is a Dynamic-Link Library? Advantages of Dynamic Linking Why Use Import Libraries? ΓòÉΓòÉΓòÉ <hidden> LINK386 - What Is a Dynamic-Link Library? ΓòÉΓòÉΓòÉ A dynamic-link library contains executable code for common functions, just as an ordinary library does. Yet code for functions in dynamic-link libraries is not copied into the executable (.EXE) file. Instead, the library itself is loaded into memory at run time, along with the .EXE file. Related Topics Advantages of Dynamic Linking Why Use Import Libraries? ΓòÉΓòÉΓòÉ <hidden> LINK386 - Advantages of Dynamic Linking ΓòÉΓòÉΓòÉ Dynamic-link libraries serve much the same purpose that standard libraries do, but they also have the following advantages: o Applications link more quickly. With dynamic linking, the executable code for a dynamic-link function is not copied into the .EXE file of the application. Instead, only an import definition is copied. o Applications require less disk space. With dynamic linking, several different program applications can access the same dynamic-link function stored in one place. Without dynamic linking, the code for the function would be repeated in every .EXE file. o Libraries and applications are independent. Dynamic-link libraries can be updated any number of times without relinking the applications that use them. If you are a user of third-party libraries, this is particularly convenient. You receive the updated .DLL file from the third-party developers, and you only need to copy the new library onto your disk. At run time, your applications automatically call the updated library functions. o Code and data segments can be shared. Code and data segments loaded from a dynamic-link library can be shared. Without dynamic linking, such sharing is not possible because each file has its own copy of all the code and data it uses. By sharing segments with dynamic linking, you can use memory more efficiently. Related Topics What Is a Dynamic-Link Library? Why Use Import Libraries? ΓòÉΓòÉΓòÉ <hidden> LINK386 - Linking without an Import Library ΓòÉΓòÉΓòÉ The figure below illustrates a simple case in which you create an application that uses a single dynamic-link library (.DLL) file. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé .OBJ and Γöé Γöé.DEF fileΓöé Γöé.DEF fileΓöé Γöé .OBJ and Γöé Γöé.LIB filesΓöé Γöé(LIBRARY)Γöé Γöé(imports)Γöé Γöé.LIB filesΓöé Γöé Γöé Γöé(exports)Γöé Γöé Γöé Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ (1) LINK386 (2) LINK386 ΓöîΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé.DLL fileΓöé Γöé .EXE file Γöé Γöé(library)Γöé Γöé(application)Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ As depicted above, linking occurs in two steps: 1. Object files (and standard libraries if any) are linked with a module definition (.DEF) file to create a .DLL file. A .DEF file is used that defines all functions exported by the .DLL file. 2. Object files (and standard libraries, if any) are linked with a .DEF file to create an application (.EXE) file. A different .DEF file is used for this step; it defines all dynamic-link functions imported (used) by the application. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Linking with an Import Library ΓòÉΓòÉΓòÉ The figure below illustrates a simple case in which you create an application that uses a single dynamic-link library (.DLL) file. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé .OBJ and Γöé Γöé.DEF fileΓöé Γöé.LIB fileΓöé Γöé .OBJ and Γöé Γöé.LIB filesΓöé Γöé(LIBRARY)Γöé Γöé(imports)Γöé Γöé.LIB filesΓöé Γöé Γöé Γöé(exports)Γöé Γöé Γöé Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÿ Γöé ΓööΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöö(2) IMPLIBΓöÇΓöÿ (1) LINK386 (3) LINK386 ΓöîΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé.DLL fileΓöé Γöé .EXE file Γöé Γöé(library)Γöé Γöé(application)Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ As depicted above, linking occurs in three steps: 1. Object files (and dynamic-link libraries) are linked with a module definition (.DEF) file to create a .DLL file. A .DEF file is used that defines all functions exported by the .DLL file. 2. The IMPLIB program is used to generate an import library (.LIB) file. IMPLIB takes as input the same module definition file used in the first step. For each export definition in the .DEF file, IMPLIB generates a corresponding import definition. (IMPLIB can also use the .DLL file generated in step 1 if you use the _export keyword in C declarations to export functions.) See IMPLIB, What Are Import Libraries?, and Why Use Import Libraries?. 3. The .LIB file generated by IMPLIB is used as input to LINK386, which creates an application (.EXE) file. This .LIB file provides LINK386 with information about imported dynamic-link functions. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Module Definition Files Basics ΓòÉΓòÉΓòÉ What Is a Module Definition File? A module definition file describes the names, attributes, exports, imports, and other characteristics of an application or library. You must use module definition files to create most applications for OS/2*. You must use module definition files to create all OS/2 dynamic-link libraries and device drivers. Module Statements A module definition file contains one or more Module Statements. These statements: o Define various attributes of the executable file o Define attributes of code and data segments o Identify functions that are imported or exported ΓòÉΓòÉΓòÉ <hidden> LINK386 - Module Definition File Example ΓòÉΓòÉΓòÉ The following module definition file gives module definitions for a dynamic-link library. It includes one source level comment and five statements. ; Sample module-definition file LIBRARY DESCRIPTION 'Sample .DEF file for a dynamic-link library' CODE PRELOAD STACKSIZE 1024 EXPORTS Init @1 Begin @2 Finish @3 Load @4 Print @5 ΓòÉΓòÉΓòÉ <hidden> LINK386 - Module Statement Rules ΓòÉΓòÉΓòÉ o If you use a NAME, LIBRARY, VIRTUAL DEVICE, or PHYSICAL DEVICE statement, it must precede all other statements in the module definition file. o You can include source level comments in the module definition file by beginning a line with a semicolon (;). Such lines are ignored. o All module definition keywords (such as NAME, LIBRARY, and OLD) must be entered in uppercase letters. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Module Statements ΓòÉΓòÉΓòÉ LINK386 has the following module definition file statements: BASE Base CODE Gives default attributes for code segments DATA Gives default attributes for data segments DESCRIPTION Describes the module EXETYPE Identifies operating system EXPORTS Defines exported functions IMPORTS Defines imported functions HEAPSIZE Specifies local heap size LIBRARY Names dynamic-link library NAME Names application OLD Preserves import information PHYSICAL DEVICE Names physical device driver PROTMODE Specifies DOS protected mode SEGMENTS Gives attributes for specific segments STACKSIZE Specifies local stack size STUB Adds DOS executable file to module VIRTUAL DEVICE Names virtual device driver ΓòÉΓòÉΓòÉ <hidden> LINK386 - BASE Statement ΓòÉΓòÉΓòÉ Syntax: BASE=n Where n is a value rounded up to the nearest multiple of 64K Indicates that each object of the module has a preferred load address starting with object 1 at this address, object 2 at the next available multiple of 64K, and so on. Internal relocation records are then applied using this addressing scheme. If the module's objects can be loaded beginning at this preferred address, then no load-time internal relocation records need be applied. If the module's objects cannot be loaded beginning at this preferred address, then the internal relocation records that have been retained in the file data will be applied. EXE files may specify a base address, but it must be 64K. If it isn't, a warning will be issued and a base address of 64K will be used anyway. ΓòÉΓòÉΓòÉ <hidden> LINK386 - CODE Statement ΓòÉΓòÉΓòÉ Syntax: CODE [attribute...] This statement defines the default attributes for code segments within the application or library. One or more attributes can appear following the CODE statement: PRELOAD or LOADONCALL Sets when code segment is loaded EXECUTEONLY or EXECUTEREAD Sets read/execute status IOPL or NOIOPL Sets I/O privilege CONFORMING or NONCONFORMING Determines 286 conformance Attribute Rules: o Only one attribute from each pair appears. If you specify neither attribute from a pair, LINK386 supplies the default, listed second in each pair above. o Attributes can appear in any order. Example The following example sets defaults for module code segments so they have I/O hardware privilege and are not loaded until accessed. CODE LOADONCALL IOPL ΓòÉΓòÉΓòÉ <hidden> LINK386 - Load Code Attributes ΓòÉΓòÉΓòÉ These attributes determine when a code segment is loaded: PRELOAD The segment is loaded automatically when the program starts. LOADONCALL The segment is not loaded until accessed (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Read/Execute Code Attributes ΓòÉΓòÉΓòÉ These attributes determine whether a code segment can be read as well as executed: EXECUTEONLY The segment can only be executed. EXECUTEREAD The segment can be both executed and read (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - I/O Privilege Code Attributes ΓòÉΓòÉΓòÉ I/O privilege code attributes determine whether a segment has I/O privilege (that is, whether it can access the hardware directly): IOPL The code segment has I/O privilege. NOIOPL The code segment does not have I/O privilege (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Conforming Code Attributes ΓòÉΓòÉΓòÉ These attributes specify whether a code segment is a 286 conforming segment: CONFORMING The segment is conforming. NONCONFORMING The segment is nonconforming (default). The concept of a conforming segment has to do with privilege level (the range of instructions that the process can execute) and is relevant only when you are writing device drivers and system level code. A conforming segment can be called from either Ring 2 or Ring 3, and the segment executes at the privilege level of the caller. ΓòÉΓòÉΓòÉ <hidden> LINK386 - DATA Statement ΓòÉΓòÉΓòÉ Syntax: DATA [attribute...] This statement defines the default attributes for data segments within the application or library. One or more attributes can appear following the DATA statement: PRELOAD or LOADONCALL Sets when data segment is loaded READONLY or READWRITE Sets read/write access NONE, SINGLE, or MULTIPLE Sets sharing attributes IOPL or NOIOPL Sets I/O privilege SHARED or NONSHARED Determines whether segment is shareable Attribute Rules o Only one attribute out of each group appears; if you specify none of the attributes in a group, the last attribute listed above for that group is generally the default. (The defaults for NONE/SINGLE/MULTIPLE and SHARED/NONSHARED vary depending on whether you are describing a dynamic-link library or application.) o Attributes can appear in any order. Example The following example defines the application data segment so that it is loaded only when it is accessed and cannot be shared by more than one copy of the program. By default, the data segment can be read and written, the automatic data segment is copied for each instance of the module, and the data segment has no I/O privilege. DATA LOADONCALL NONSHARED ΓòÉΓòÉΓòÉ <hidden> LINK386 - Load Data Attributes ΓòÉΓòÉΓòÉ These attributes determine when a data segment is loaded: PRELOAD The segment is loaded automatically when the program starts. LOADONCALL The segment is not loaded until accessed (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Read/Write Data Attributes ΓòÉΓòÉΓòÉ These attributes determine the access rights to a data segment: READONLY The segment can only be read. READWRITE The segment can be both read and written to (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Sharing Data Attributes ΓòÉΓòÉΓòÉ These attributes determine how the automatic data segment can be shared: NONE No automatic data segment is created. SINGLE A single automatic data segment is shared by all instances of the module. In this case, the module is said to have solo data. This keyword is the default for dynamic-link libraries. MULTIPLE The automatic data segment is copied for each instance of the module. In this case, the module is said to have instance data. This keyword is the default for applications. The automatic data segment is the physical segment represented by the group name DGROUP. This segment group makes up the physical segment that contains the local stack and heap of the application. ΓòÉΓòÉΓòÉ <hidden> LINK386 -I/O Privilege Data Attributes ΓòÉΓòÉΓòÉ These attributes determine whether data segments have I/O privilege (that is, whether they can access the hardware directly): IOPL The data segments have I/O privilege. NOIOPL The data segments do not have I/O privilege (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Shareable Data Attributes ΓòÉΓòÉΓòÉ These attributes determine whether all instances of the program can share a READWRITE data segment: SHARED One copy of the data segment is loaded and shared among all processes accessing the module (default for dynamic-link libraries). NONSHARED The segment cannot be shared, and must be loaded separately for each process (default for applications). Under OS/2*, this field is ignored if READONLY is specified, since READONLY data segments are always shared. ΓòÉΓòÉΓòÉ <hidden> LINK386 - SEGMENTS Statement ΓòÉΓòÉΓòÉ Syntax: SEGMENTS segmentdefinitions This statement defines the attributes of one or more segments in the application or library on a segment-by-segment basis. The attributes specified by this statement override defaults set in CODE and DATA statements. The SEGMENTS keyword marks the beginning of the segment definitions. This keyword can be followed by one or more segment definitions, each on a separate line (limited by the number set by the LINK386 /SE option, or 128 if the option is not used). See Set Max Number Segments Option Segment-Definition Syntax ['] segmentname ['] [CLASS 'classname'] [attribute...] Each segment definition begins with <segmentname>, optionally enclosed in single quotation marks ('). The quotation marks are required if <segmentname> conflicts with a module definition keyword, such as CODE or DATA. The CLASS keyword specifies the class of the segment. Single quotation marks (') are required for <classname>. If you do not use the CLASS argument, LINK386 assumes that the class is CODE. One or more attributes can follow. The default attribute is listed last. PRELOAD or LOADONCALL Determines when segment is loaded READONLY or READWRITE Sets read/write access EXECUTEONLY or EXECUTEREAD Sets read/execute status IOPL or NOIOPL Sets I/O privilege CONFORMING or NONCONFORMING Determines 286 conformance MIXED1632 Specify Mixed 16 and 32-Bit Segments ALIAS Specify that segment is aliased SHARED or NONSHARED Specify that segment is shared Attribute Rules o Only one attribute from each pair appears. If you specify neither attribute from a pair, LINK386 supplies the default (listed second in each pair above). o Attributes can appear in any order. Example SEGMENTS cseg1 CLASS 'mycode' IOPL cseg2 EXECUTEONLY PRELOAD CONFORMING dseg CLASS 'data' LOADONCALL READONLY This example specifies segments named cseg1, cseg2, and dseg. The first segment is assigned class mycode and the second is assigned CODE by default. Each segment is given different attributes. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Load Segments Attributes ΓòÉΓòÉΓòÉ These attributes determine when a segment is loaded: PRELOAD The segment is loaded automatically when the program starts. LOADONCALL The segment is not loaded until accessed (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Read/Write Segments Attributes ΓòÉΓòÉΓòÉ These attributes determine the access rights to a data segment: READONLY The segment can only be read. READWRITE The segment can be both read and written to (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Read/Execute Segments Attributes ΓòÉΓòÉΓòÉ These attributes determine whether a code segment can be read as well as executed: EXECUTEONLY The segment can only be executed. EXECUTEREAD The segment can be both executed and read (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - I/O Privilege Segments Attributes ΓòÉΓòÉΓòÉ These attributes determine whether a segment has I/O privilege (that is, whether it can access the hardware directly): IOPL The segment has I/O privilege. NOIOPL The segment does not have I/O privilege (default). ΓòÉΓòÉΓòÉ <hidden> LINK386 - Conforming Segments Attributes ΓòÉΓòÉΓòÉ These attributes specify whether a code segment is a 286 conforming segment: CONFORMING The segment is conforming. NONCONFORMING The segment is nonconforming (default). The concept of a conforming segment has to do with privilege level (the range of instructions that the process can execute). Conforming attributes are relevant only when you are writing device drivers and system-level code. A conforming segment can be called from either Ring 2 or Ring 3, and the segment executes at the privilege level of the caller. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Specify Mixed 16 and 32-Bit Segments ΓòÉΓòÉΓòÉ Sometimes it is necessary to mix 16-bit code with 32-bit code. When you must create groups that allow such mixing, LINK386 requires that you declare the segments in that group as MIXED1632. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Specify that Segment is Aliased ΓòÉΓòÉΓòÉ Segments flagged with the ALIAS keyword can be addressed using the 16-bit segmented method (_far16), or the 32-bit linear method. The loader must prepare an additional segment selector for each segment designated with the ALIAS keyword. This new segment selector allows for 16-bit addressing. Example: SEGMENTS _CODE ALIAS The statement above specifies that the segment _CODE can be called using 16-bit far calls and 32-bit near calls. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Specify that Segment is Shared ΓòÉΓòÉΓòÉ These attributes determine if the segment can be shared by other processes. SHARED One copy of the data segment is loaded and shared among all processes accessing the module (default for dynamic-link libraries). NONSHARED The segment cannot be shared, and must be loaded separately for each process (default for applications). ΓòÉΓòÉΓòÉ <hidden> LINK386 - DESCRIPTION Statement ΓòÉΓòÉΓòÉ Syntax: DESCRIPTION 'text' This statement inserts the specified text into the application or library. The DESCRIPTION statement is useful for embedding source control or copyright information into an application or library. The <text> field is a one line string enclosed in single quotation marks. Example The following example inserts the text Template Program into the application or library being defined. DESCRIPTION 'Template Program' ΓòÉΓòÉΓòÉ <hidden> LINK386 - EXETYPE Statement ΓòÉΓòÉΓòÉ Syntax: EXETYPE [OS2 | WINDOWS | UNKNOWN] This statement specifies under which operating system the application (or dynamic-link library) is to run. This statement is optional and provides an additional degree of protection against the program being run in an incorrect operating system. The EXETYPE keyword can be followed by a descriptor of the operating system: OS2 OS/2* applications and dynamic-link libraries (default) WINDOWS Windows** applications UNKNOWN Other applications The effect of EXETYPE is to set bits in the header that identify operating-system type. Operating-system loaders can check these bits. ΓòÉΓòÉΓòÉ <hidden> LINK386 - EXPORTS Statement ΓòÉΓòÉΓòÉ Syntax: EXPORTS exportdefinitions This statement defines the names and attributes of the functions exported to other modules and of the functions that run with I/O privilege. Note: The term export refers to the process of making a function available to other run-time modules. By default, functions are hidden from other modules at run time. Normally, the EXPORTS statement is meaningful only for functions within dynamic-link libraries and for functions that execute with I/O privilege. The EXPORTS keyword marks the beginning of the export definitions. Each definition is entered on a separate line. You need to give an export definition for each dynamic-link routine you want to make available to other modules. Export-Definition Syntax entryname [=internalname] [@ord[RESIDENTNAME]] [pwords] <entryname> The function name as it is known to other modules. <internalname> The actual name of the export function as it appears within the module itself; by default, this name is the same as <entryname>. <ord> The function's ordinal position within the module definition table. If this field is used, the function's entry point can be invoked by name or by ordinal. Use of ordinal positions is faster and may save space. RESIDENTNAME Indicates that the function's name be kept resident in memory at all times. This keyword is applicable only if <ord> is used. If <ord> is not used, OS/2* automatically keeps the names of all exported functions resident in memory by default. <pwords> The total size of the function's parameters, as measured in words (bytes divided by two). This field is required only if the function executes with I/O privilege. When a function with I/O privilege is called, OS/2 consults <pwords> to determine how many words to copy from the caller's stack to the I/O-privileged function's stack. Example EXPORTS SampleRead = read2bin @8 StringIn = str1 @4 RESIDENTNAME CharTest 6 This example defines three export functions: o SampleRead o StringIn o CharTest The first two functions can be accessed either by their exported names or by an ordinal number. Note that in the module's own source code, these functions are actually defined as read2bin and str1, respectively. The last function runs with I/O privilege and therefore is given with the total size of the parameters - six words. ΓòÉΓòÉΓòÉ <hidden> LINK386 - IMPORTS Statement ΓòÉΓòÉΓòÉ Syntax: IMPORTS importdefinitions This statement defines the names of the functions imported for the application or library. Note: The term import refers to the process of declaring that a symbol is defined in another run-time module (a dynamic-link library). Typically, LINK386 uses an import library (created by the IMPLIB utility) to resolve external references to dynamic-link symbols. However, the IMPORTS statement provides an alternative for resolving these references within a module. The IMPORTS keyword marks the beginning of the import definitions. This keyword is followed by one or more import definitions, each on a separate line. The only limit on the number of import definitions is that the total amount of space required for their names must be less than 64K. Each import definition corresponds to a particular function. Import-Definition Syntax [internalname=]modulename.entry <internalname> The name that the importing module uses to call the function. Thus, <internalname> appears in the source code of the importing module, although the function can have a different name in the module where it is defined. By default, internalname is the same as <entry>. <modulename> The name of the application or library that contains the function. <entry> The function to be imported; can be a name or an ordinal value. (Ordinal values are set in an EXPORTS statement.) If an ordinal value is given, then <internalname> is required. Note: A given function has a name for each of three different contexts. The function has a name used by the exporting module (where it is defined), a name used as an entry point between modules, and a name as it is used by the importing module (where it is called). If neither module uses the optional <internalname> field, the function has the same name in all three contexts. If either of the modules uses the <internalname> field, the function may have more than one distinct name. Syntax: IMPORTS Sample.SampleRead SampleA.SampleWrite ReadChar = Read.1 This example defines three functions to be imported: o SampleRead o SampleWrite o A function that has been assigned an ordinal value of 1 The functions are found in the modules Sample, SampleA, and Read, respectively. The function from the Read module is referred to as ReadChar in the importing module. The original name of the function, as it is defined in the Read module, may or may not be known. ΓòÉΓòÉΓòÉ <hidden> LINK386 - HEAPSIZE Statement ΓòÉΓòÉΓòÉ Syntax: HEAPSIZE bytes | MAXVAL This statement defines the size of the application's local heap in bytes. This value affects the size of the automatic data segment. The field <bytes> contains any positive integer. You can enter <bytes> in decimal, octal, or hexadecimal radix. See Entering Numeric Arguments. Instead of entering a number for <bytes>, you can enter the keyword MAXVAL. This sets the heap size such that the default data segment DGROUP is exactly 64K. MAXVAL is useful in bound applications in which you want to force a 64K requirement for DGROUP. Example HEAPSIZE 4000 This example sets the local heap to 4,000 bytes. ΓòÉΓòÉΓòÉ <hidden> LINK386 - LIBRARY Statement ΓòÉΓòÉΓòÉ Syntax: LIBRARY [libraryname] [initialization] [termination] This statement identifies the executable file as a dynamic-link library and optionally defines the name and library module initialization required. If <libraryname> is given, it becomes the name of the library as it is known by OS/2*. This name can be any valid file name. If <libraryname> is not given, the name of the executable file - with the extension removed - becomes the name of the library. If <initialization> is given, it defines the library initialization required and can be one of the values below. If omitted, <initialization> defaults to INITGLOBAL. INITGLOBAL The library initialization routine is called only when the library module is initially loaded into memory. Using this keyword without a termination flag implies TERMGLOBAL for DLLs with 32-bit entry points. INITINSTANCE The library initialization routine is called each time a new process gains access to the library. Using this keyword without a termination flag implies TERMINSTANCE for DLLs with 32-bit entry points. If <termination> is given, it defines the library termination required and can be one of the values below. If omitted, <initialization> defaults to TERMGLOBAL. The termination flag can only apply to DLLs with 32-bit entry points. TERMGLOBAL The library termination routine is called only when the library module is unloaded from memory. Using this keyword without an initialization flag implies INITGLOBAL. TERMINSTANCE The library termination routine is called each time a process relinquishes access to the library. Using this keyword without an initialization flag implies INITINSTANCE. If the LIBRARY statement is included in a module definition file, the NAME statement cannot appear. If no LIBRARY statement appears, the module definition file describes an application. The following example assigns the name calendar to the dynamic-link library and specifies that library initialization be performed each time a new process gains access. LIBRARY calendar INITINSTANCE ΓòÉΓòÉΓòÉ <hidden> LINK386 - NAME Statement ΓòÉΓòÉΓòÉ Syntax: NAME [appname][apptype] This statement identifies the executable file as an application and optionally defines the name and type. If <appname> is given, it becomes the name of the application as it is known by OS/2*. This name can be any valid file name. If <appname> is not given, the name of the executable file - with the extension removed - becomes the name of the application. If <apptype> is given, it defines the type of application: WINDOWAPI Presentation Manager application. The application uses the API provided by the Presentation Manager and must be executed in the Presentation Manager environment. WINDOWCOMPAT Application compatible with Presentation Manager. The application can run inside the Presentation Manager, or it can run in a separate screen group. An application can be of this type if it uses the proper subset of OS/2 video, keyboard, and mouse functions supported in the Presentation Manager applications. NOTWINDOWCOMPAT Application that is not compatible with the Presentation Manager and must operate in a separate screen group from the Presentation Manager. If the NAME statement appears, the LIBRARY, VIRTUAL DEVICE and PHYSICAL DEVICE statements cannot appear. If none of these statements appear, the module definition file is assumed to describe an application. Example The following example assigns the name calendar to the application being defined. NAME calendar WINDOWCOMPAT This application is Presentation Manager-compatible. ΓòÉΓòÉΓòÉ <hidden> LINK386 - OLD Statement ΓòÉΓòÉΓòÉ Syntax: OLD 'filename' This statement directs LINK386 to search another dynamic-link module for export ordinals. Exported names in the current module that match exported names in the OLD module are assigned ordinal values from that module unless one of the following conditions is in effect: o The name in the OLD module has no ordinal value assigned. o An ordinal value is explicitly assigned in the current module. This statement is useful for preserving export ordinal values throughout successive versions of a dynamic-link module. The OLD statement has no effect on application modules. Related Topics EXPORTS Statement IMPORTS Statement ΓòÉΓòÉΓòÉ <hidden> LINK386 - PHYSICAL DEVICE statement ΓòÉΓòÉΓòÉ Syntax: PHYSICAL DEVICE [drivername] This statement identifies the executable file as a physical device driver. If <drivername> is given, it becomes the name of the driver as it is known by OS/2*. This name can be any valid file name. If <drivername> is not given, the name of the executable file - with the extension removed - becomes the name of the driver. ΓòÉΓòÉΓòÉ <hidden> LINK386 - PROTMODE Statement ΓòÉΓòÉΓòÉ Syntax: PROTMODE This statement specifies that the module runs only in protected mode and not in Windows** or dual mode. This statement is always optional and permits a protected mode only application to omit some information from the executable file header. If this statement is not included in the module definition file, LINK386 assumes the application can be run in either real or protected mode. ΓòÉΓòÉΓòÉ <hidden> LINK386 - STACKSIZE Statement ΓòÉΓòÉΓòÉ Syntax: STACKSIZE number This statement performs the same function as the LINK386 /ST option; if both are used, the STACKSIZE statement overrides the /ST option. See Control Stack Size Option (/ST). The field <number> contains a positive integer. You can specify <number> in decimal, octal, or hexadecimal radix. See Entering Numeric Arguments. Example STACKSIZE 4096 This example allocates 4,096 bytes of local-stack space. ΓòÉΓòÉΓòÉ <hidden> LINK386 - STUB Statement ΓòÉΓòÉΓòÉ Syntax: STUB 'filename' This statement adds a DOS executable file to the beginning of the application or library being created. The stub is invoked whenever the module is executed under DOS. Typically, the stub displays a message and terminates execution. By default, LINK386 adds its own standard stub for this purpose. The field <filename> specifies the DOS executable file to be added. LINK386 looks for <filename> in the current directory and in the directories specified by the PATH environment variable. Example STUB 'STOPIT.EXE' This example appends the DOS executable file STOPIT.EXE to the beginning of the module. STOPIT.EXE is executed when the module is run under DOS. ΓòÉΓòÉΓòÉ <hidden> LINK386 - VIRTUAL DEVICE Statement ΓòÉΓòÉΓòÉ Syntax: VIRTUAL DEVICE [drivername] This statement identifies the executable file as a virtual device driver. If <drivername> is given, it becomes the name of the driver as it is known by OS/2*. This name can be any valid file name. If <drivername> is not given, the name of the executable file - with the extension removed - becomes the name of the driver. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Error Messages ΓòÉΓòÉΓòÉ Format of Error Messages There are three types of LINK386 error messages: o Fatal errors cause LINK386 to stop running. They have the following format: location : fatal error L1xxx : message text o Nonfatal errors indicate problems in the executable file. LINK386 produces the executable file and sets the error bit in the header for the OS/2* environment. This means that the executable file cannot be run from OS/2. Nonfatal error messages have the following format: location : error L2xxx : message text o Warnings indicate possible problems in the executable file. LINK386 produces the executable file, but does not set the error bit in the header for the OS/2 environment. Warnings have the following format: location : warning L4xxx : message text In all these messages, location is the input file associated with the error, or it is LINK386 itself if there is no input file. The message text is the actual text message that LINK386 generates. When the input file is a module definition file, the line number is included, as in this example: myfile.def(3): fatal error L1030: missing internal name When the input file is an object file or library file and has a module name, the module name is enclosed in parentheses, as in the following examples: SLIBCE.LIB(_file) MAIN.OBJ(main.c) TEXT.OBJ Error Message Descriptions LINK386 Fatal Error Messages (part 1) 1001 - 1049 LINK386 Fatal Error Messages (part 2) 1050 - 1098 LINK386 Fatal Error Messages (part 3) 1100 - 1130 LINK386 Nonfatal Error Messages 2000 - 2063 LINK386 Warning Error Messages 4000 - 4094 ΓòÉΓòÉΓòÉ <hidden> LINK386 - Fatal Error Messages (Part 1) 1001 - 1049 ΓòÉΓòÉΓòÉ L1001 option : option name ambiguous Explanation: A unique option name does not appear after the option indicator (/). Example: The command LINK386 /N main; produces this error because LINK386 cannot tell which of the seven options beginning with the letter N is intended. Action: Retry using the correct minimum option abbreviation. L1004 option : invalid numeric value Explanation: An incorrect value appeared for one of the LINK386 options. This might be because a character string has been entered for an option that requires a numeric value or because the proper numeric prefix (for example, 0x for hexidecimal) was not used for a numeric value. Action: Retry with a numeric value. L1006 option : stack size exceeds 65,535 bytes Explanation: The size you specified for the stack in the /STACK option of the link command is more than 65,535 bytes. Action: Retry with a stack size of less than or equal to 65,535 bytes. L1008 option : segment limit set too high Explanation: The specified limit on the /SEGMENTS option is greater than 16 375. Action: Retry with a limit in the range 1 to 16 375. L1020 no object modules specified Explanation: You did not specify any object file names to the linker. Action: Restart LINK386, including at least one object file name. L1021 cannot nest response files Explanation: A response file has been named within another response file. You have used @filename within the response file. The @ symbol is reserved by LINK386 to signify a response file name. Action: Edit the response file to remove the nested response file. L1022 response line too long Explanation: A line in an automatic response file is longer than 256 characters. Action: Edit the line to make it shorter than 256 characters. Response files can contain more than one line. L1023 terminated by user Explanation: You pressed Ctrl+C or Ctrl+Break. Action: Your action has terminated LINK386. Restart if necessary. L1030 missing internal name Explanation: You have not specified an internal name for an import in the module definition file. Action: Edit the module definition file, giving an internal name so that LINK386 can identify references to the import. L1031 module description redefined Explanation: You have used the DESCRIPTION keyword for a module in the module definition file more than once. Action: Edit the module definition file, deleting the extra descriptions. L1032 module name redefined Explanation: You have defined a module name more than once with the NAME or LIBRARY keyword in the module definition file. Action: Edit the module definition file, checking the module name definitions. L1033 input line too long; number characters allowed Explanation: The input line contains more than number characters. Action: Retry the command with fewer characters on the input line. L1040 too many exported entries Explanation: You have tried to export more than 65535 names. Action: Retry with fewer names, creating an additional executable module if necessary. L1041 resident-name table overflow Explanation: The total length of all your resident-names, together with an overhead of 3 bytes for each name, is greater than 65,534. Action: Reduce the number or the length of your resident names. L1042 nonresident-name table overflow Explanation: The total length of all your nonresident-names, together with an overhead of 3 bytes for each name, is greater than 65,534. Action: Reduce the number or the length of your nonresident-names. L1043 relocation table overflow Explanation: There are more than 65,535 load-time relocations for a single segment. Action: Reduce the number of relocations in the source files and recompile or reassemble them. Interframe references generate load-time relocations. L1044 imported-name table overflow Explanation: The total length of all your imported-names, together with an overhead of 1 byte for each name, is greater than 65,535 bytes. Action: Reduce the number or the length of your imported-names. L1045 too many TYPDEF records Explanation: An object module contains more than 255 TYPDEF records. These records describe communal variables. This error can only appear with programs produced by compilers that support communal variables. Action: Reduce the number of TYPDEF records, breaking the module into smaller parts, if necessary. L1046 too many external symbols in one module Explanation: An object module specifies more than the limit of 1023 external symbols. Action: Reduce the number of external symbols, breaking the module into smaller parts, if necessary. L1047 too many group, segment, and class names in one module Explanation: The program module contains too many group, segment, and class names. Action: Reduce the number of groups, segments, or classes, and re-create the object files. L1048 too many segments in one module Explanation: An object module has more than 255 segments. Action: Reduce the number of segments, splitting the module or combining some segments. L1049 too many segments Explanation: The program has more than the maximum number of segments. The /SEGMENTS option specifies the maximum allowed number; the maximum is 16375. Action: Restart LINK386 using the /SEGMENTS option with an appropriate number of segments. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Fatal Error Messages (Part 2) 1050 - 1098 ΓòÉΓòÉΓòÉ L1050 too many groups in one module Explanation: LINK386 found more than 32 group definitions (GRPDEF) in a single module. Action: Reduce the number of group definitions by splitting the module, by eliminating one or more group definitions, or combining group definitions. L1051 too many groups Explanation: The program defines more than 32 groups in addition to DGROUP. Action: Reduce the number of group definitions by splitting the module, by eliminating one or more group definitions, or combining group definitions. L1052 too many libraries Explanation: You tried to link with more than 32 libraries. Action: Combine libraries, or use modules that require fewer libraries. L1053 out of memory for symbol table Explanation: The program has more symbolic information, such as public, external, segment, group, class, and file names, than the amount that could fit in available real memory. Maximum is 65,535 bytes. Action: Combine modules or segments and recreate the object files. Eliminate as many public symbols as possible or use shorter names. L1054 requested segment limit too high Explanation: There is not enough memory to allocate the necessary tables for the amount of segments requested. Action: Reduce the number of segments by combining or creating additional executable modules. L1057 data record too large Explanation: A LEDATA record (in an object module) contained more than 1024 bytes of data. This is a translator (compiler or assembler) error. Action: Note which translator (compiler or assembler) produced the incorrect object module and the circumstances, and contact your supplier. L1060 program exceeds number bytes Explanation: There is not enough memory to process all segments. Action: Reduce the number of segments by combining or creating additional executable modules. L1063 out of memory for debugging information Explanation: LINK386 was given too many object files with debug information, and ran out of space to store them. Action: Reduce the number of object files that have debug information. L1064 out of memory - name heap exhausted Explanation: The linker ran out of heap space; name = near or far. Action: Reduce the number of background processes or install more memory. L1070 name: segment size exceeds 64K Explanation: A single segment contains more than 64K of code or data. This could be because you attempted to combine identically named segments. Action: Try compiling (or assembling) and linking using a larger memory model or breaking up the named segment. L1071 segment _TEXT larger than 65,520 bytes Explanation: This error is likely to occur only in small-model C programs, but it can occur when any program with a segment named _TEXT is linked using the /DOSSEG option of the LINK386 command. Small-model C programs must reserve code addresses 0 and 1; the reserve is increased to 16 for alignment purposes. Action: Make the program source code smaller, or change to a larger memory model. L1072 common area longer than 65,536 bytes Explanation: The program has more than 64K of communal variables. This error occurs only with programs produced by compilers that support communal variables. Action: Rewrite your program using fewer or smaller communal variables. L1073 file-segment limit exceeded Explanation: There are more than 255 physical or file segments. Action: Reduce the number of physical or file segments. You could use the Pack Contiguous Data (/PACKD) option for combining data segments or the Pack Contiguous Code (/PACKC) option for combining code segments. L1074 name: group larger than 64K Explanation: A group contains segments that total more than 65,536 bytes. Action: Reduce the number or size of segments or remove segments from the group. L1075 entry table larger than 65,535 bytes Explanation: You have exceeded a linker table size limit because of an excessive number of entry names. Action: Reduce the number of names in the modules that you are linking or create additional executable modules. L1076 name: segment size exceeds numberM Explanation: The named segment is larger than the specified size. Action: Break the segment into smaller segments and try again. L1077 common area longer than 4G-1 bytes Explanation: The space for the C languages common area is too big. Action: If the load module is an .EXE, consider putting some routines in .DLL; otherwise, link without debugging information or create additional executable modules. L1080 cannot open list file Explanation: The disk or a directory is full, or an invalid file name was specified. Action: Check that the file name specified is correct. Delete or move files to make space and restart LINK386. L1081 out of space for run file Explanation: The disk on which the .EXE file is being written is full. Action: Delete or move files to make space and restart LINK386. L1082 name: stub file not found Explanation: The stub file specified in the module definition file could not be found. Action: Check that the correct path to the stub file has been specified. L1083 cannot open run file - reason Explanation: The run file could not be opened for the stated reason. Action: Correct the problem and restart LINK386. L1084 cannot create temporary file Explanation: The disk or a directory is full. Action: Delete or move files to make space and restart LINK386. L1085 cannot open temporary file - reason Explanation: The run file could not be opened for the stated reason. Action: Correct the problem and restart LINK386. L1086 scratch file missing Explanation: LINK386 was unable to open the temporary linker output file. Action: Note the conditions when the error occurs and contact your supplier. L1087 unexpected end-of-file on scratch file Explanation: The disk with the temporary linker output file has been removed or is corrupted. Action: Replace the disk containing the library and restart LINK386. L1088 out of space for list file Explanation: The disk on which the listing file is being written is full. Action: Delete or move files to make space and restart LINK386. L1089 filename: cannot open response file Explanation: LINK386 cannot find the specified response file. This usually indicates a typing error. Action: Include the drive specifier or path, or both, for the response file. L1091 unexpected end-of-file on library Explanation: The disk containing the library has probably been removed or is corrupted. Action: Replace the disk containing the library and restart LINK386. L1092 cannot open module definition file Explanation: The specified module definition file cannot be opened, or an invalid file name was specified. Action: Check that the specified file name is correct. Include the drive specifier or path, or both, for the module definition file. L1093 name: object not found Explanation: LINK386 could not open the object module you specified. Action: Specify full path name or directory in which object module resides. L1096 unexpected end-of-file Explanation: LINK386 encountered an end-of-file character while reading an input file AND expected more information. Action: Check input files for errors and relink. L1097 I/O error - string Explanation: The linker encountered the I/O error shown while reading from a file. Action: Make sure the file is not corrupted or on a bad disk sector and relink. L1098 cannot open include file filename - reason Explanation: LINK386 could not open the include file for the stated reason. Action: Correct the problem and restart LINK386. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Fatal Error Messages (Part 3) 1100 - 1130 ΓòÉΓòÉΓòÉ L1100 stub .EXE file invalid Explanation: The stub file specified in the module definition file is not a valid .EXE file. Action: Ensure that the stub file is an executable file. L1101 invalid object module Explanation: One of the object modules was incorrectly formed during compilation or assembly. Action: Recompile or reassemble your source code. If the error persists, contact your supplier. L1102 unexpected end-of-file Explanation: An invalid format for a library was found. Action: Restore the library file from your backup disk and restart LINK386. If this does not work, rebuild your library or contact your supplier. L1103 name: attempt to access data outside segment bounds Explanation: A data record in an object module specified data extending beyond the end of a segment. This is a translator error. Action: Note which translator (compiler or assembler) produced the incorrect object module and the circumstances, and contact your supplier. L1104 filename: not valid library Explanation: The specified file is not a valid library file. This error causes LINK386 to stop running. Action: Ensure that the named file is a valid library file and restart LINK386. If this does not work, rebuild your library or contact your supplier. L1105 invalid object due to aborted incremental compile Explanation: An object file from an aborted compile is trying to be linked. Action: Recompile the source that produced the bad compile and then relink. L1106 unknown COMDAT allocation type for name; record ignored Explanation: The COMDAT (record in .OBJ) allocation type for the named COMDAT was not valid. Action: Recompile or reassemble .OBJ and try again. If that does not work, contact your supplier. L1107 unknown COMDAT selection type for name; record ignored Explanation: The COMDAT (record in .OBJ) selection type for the named COMDAT is not valid. Action: Recompile or reassemble .OBJ and try again. If that does not work, contact your supplier. L1108 invalid format of debugging information Explanation: An error was detected in a segment that contains debug information. Action: Recompile or reassemble and try again. If that does not work, try relinking without using the /DE or /CO options. L1113 unresolved COMDEF; internal error Explanation: LINK386 encountered a COMDEF (record in .OBJ) in pass 2 that was not defined in pass 1. Action: Recompile or reassemble and try again. If that does not work, contact your supplier. L1114 unresolved COMDAT name: internal error Explanation: LINK386 found specified COMDAT in pass 2 that does not correspond to COMDATs found in pass 1. Action: Recompile or reassemble and try again. If that does not work, contact your supplier. L1117 unallocated COMDAT name; internal error Explanation: The linker encountered COMDAT in pass 2 for which space was not allocated during pass 1. Action: Recompile or reassemble and try again. If that does not work, contact your supplier. L1121 name: group larger than 4G-1 bytes Explanation: The group indicated is too large. Action: Recompile or reassemble and try again. Remove segments from the group or create additional executables if necessary. L1123 name: segment defined both 16- and 32-bit Explanation: The segment named was defined as both 16-bit and 32-bit. Action: Create two segments (one for 16-bit, one for 32-bit), or make sure the segment is defined one way and relink. L1126 conflicting IOPL-parameter-words value Explanation: The IOPL parameter words in the .DEF file does not exactly match those in the corresponding EXPDEF object record. Action: Make sure .DEF file coincides with that defined in .OBJ. Relink. L1128 too many nested include files in module-definition file Explanation: The .DEF file exceeded a nesting level. Action: Combine some nestings into one .DEF file and try again. L1129 missing or bad include file name Explanation: LINK386 could not find a file included by .DEF file. Action: Make sure the file exists and can be located and that any path is specified correctly. Try again. L1130 internal fix-up applied to undefined area at offset in object number Explanation: LINK386 attempted to apply an internal fix-up beyond the defined limits of the object. Action: This is probably a compiler or assembler error. Revise the source file and re-create the object file. If that does not work, contact your supplier. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Nonfatal Error Messages 2000 - 2063 ΓòÉΓòÉΓòÉ L2000 imported starting address Explanation: A MODEND, or starting address record, referred to an imported name. Imported program-starting addresses are not supported. Action: The starting address record must refer to a nonimported name. Edit the source file and recompile or reassemble. L2002 fix-up overflow at location in segment name Explanation: A fixup overflow occurred near location, in the named segment. See Conditions That Can Cause LINK386 Error 2002 Action: Revise the source file and re-create the object file. If that does not work, contact your supplier. L2003 intersegment self-relative fix-up at location in segment name Explanation: LINK386 detected an intersegment self-relative fix-up. A self-relative fix-up cannot be in another segment. This is probably a compiler or assembler error. Action: Revise the source file and re-create the object file. If that does not work, contact your supplier. L2005 fix-up type unsupported at location in segment name Explanation: LINK386 detected an unsupported fixup type. This is probably a compiler or assembler error. Action: Revise the source file and re-create the object file. If that does not work, contact your supplier. L2010 Revise the source file and re-create the object file. If that does not work, contact your supplier. too many fix-ups in LIDATA record Explanation: There are more fixups applying to a LIDATA record than will fit into the LINK386's 1024 byte buffer. The buffer is divided between the data in the LIDATA record itself and the run-time relocation items. These are 8 bytes each, so the maximum varies from 0 to 128. This is probably a compiler error. Action: Revise the source file and re-create the object file. If that does not work, contact your supplier. L2011 name: NEAR/HUGE conflict Explanation: There are conflicting NEAR and HUGE attributes for a communal variable. This error can occur only with programs produced by compilers that support communal variables. Action: Specify only one of these attributes. L2012 name: array-element size mismatch Explanation: A far communal array has been declared with two or more different array-element sizes (for example, an array declared once as an array of characters and once as an array of real numbers). This error occurs only when using compilers that support far communal arrays. Action: Match the definitions and re-create the object module or modules. L2013 LIDATA record too large Explanation: A LIDATA record in an object module contains more than 512 bytes of data. It is likely that one of your assembler modules contains a complex structure definition or a series of deeply-nested DUP operators. (LIDATA is a DOS term.) Example: The following structure definition causes this error: alpha DB 10DUP(11 DUP(12 DUP(13 DUP(...)))) Action: Simplify the structure definition and reassemble the module. L2022 name (alias internalname) : export undefined Explanation: A name has been directed to be exported but is not defined anywhere. Action: Edit the source file and define the export. L2023 name (alias internalname) : export imported Explanation: An imported name has been directed to be exported. Items that are not in the source file itself cannot be exported. You cannot export this imported name. Action: Edit the source file to not export the imported name. L2024 name: special symbol already defined Explanation: Your program defined a symbol name that LINK386 already used for one of its low-level symbols. For example, the linker generates special names for overlay support. Action: Edit the source file and choose another name for the symbol. L2025 name: symbol defined more than once Explanation: A symbol has been defined more than once in the object file. Action: Edit the source file, removing the extra symbol definition. L2026 entry ordinal number, name name : multiple definitions for same ordinal Explanation: More than one entry point name has been assigned to the same ordinal in the module definition file. Action: Edit the module definition file to correct the usage of the ordinal. L2027 number: ordinal too large for export Explanation: You tried to export more than 3072 names or indicated too large of an ordinal. Action: Edit the source file or define smaller ordinals in the module definition file. L2029 string: unresolved external Explanation: A symbol declared to be external in one or more modules was not found among the given objects and libraries. Action: Supply files that will resolve these external calls. L2030 starting address not code (use class `CODE') Explanation: You specified a starting address to LINK386 that is not within a segment of type 'CODE.' Action: Reclassify the segment to CODE, or correct the starting point. L2044 string: symbol multiple defines, use /NOE Explanation: The symbol shown was defined more than once, perhaps for different things. Action: Recompile with the /NOEXDICTIONARY option. L2047 IOPL attribute conflict - segment: name in group:name Explanation: The segment indicated within the group shown has different IOPL attributes from the rest of the segments in the group. Action: Remove the segment from the group or make sure all segments have the same IOPL attributes. Relink. L2050 use16/use32 attribute conflict - segment:name in group:name Explanation: The segment indicated within the group shown has a different USE16/USE32 attribute from the rest of the segments in the group. Action: Remove the segment from the group or make sure all segments have the same USE16/USE32 attribute. L2052 name: unresolved external - possible calling convention mismatch Explanation: LINK386 encountered an undefined external, which could be a fast-call/C-call mismatch. Action: Make sure the external is defined and called the same way (for example, all C-calls). L2053 call gates are NOT allowed in 32-bit object if its size exceeds 64K - memory object number number Explanation: The memory object indicated is larger than 64K and uses call gates. Action: Remove the call gates or break the object into smaller portions. Relink. L2054 data for invalid page in segment name Explanation: LINK386 encountered data past the defined end of initialized data in the segment indicated. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your supplier. L2055 fix-up for invalid page at location in segment name Explanation: LINK386 encountered a fixup past the defined end of initialized data in the segment indicated. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your L2056 object type conflict - segment: name in group: name Explanation: The segment indicated within the group shown has a different TYPE attribute from the rest of the segments in the group. Action: Remove the segment from the group or make sure all segments have the same TYPE attribute. L2057 duplicate of name with different size found; record ignored Explanation: LINK386 encountered two COMDAT records with the selection type "SAME SIZE." The records have the same name but have different sizes. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your L2058 different duplicate of name found; record ignored Explanation: LINK386 encountered two COMDAT records with the selection type "EXACT." The records have the same name but have different sizes. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your L2059 size of the data block associated with name exceeds 4G Explanation: LINK386 encountered a continuation COMDAT record whose additional size made the communal data too large. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your L2061 no space for the data block associated with record name inside the segment name Explanation: While being allocated space for a COMDAT record inside the segment indicated, the segment grew larger than 64K. Action: Make the segment smaller or move communal data into a different segment. L2062 continuation of COMDAT name has conflicting attributes; record ignored Explanation: While concatenating the COMDAT record indicated, LINK386 found attributes that differ from those defined in the initial COMDAT record. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your L2063 name allocated in undefined segment Explanation: LINK386 encountered a COMDAT record in an undefined explicit allocation segment. Action: The .OBJ is probably corrupted. Recompile or reassemble and try again. If that does not work, contact your supplier. ΓòÉΓòÉΓòÉ <hidden> LINK386 - Warning Error Messages 4000 - 4087 ΓòÉΓòÉΓòÉ L4000 seg disp. included near location in segment name Explanation: This error is caused by using the LINK386 Warn Fixup (/WA) option. Action: The segment name and the location offset is displayed. L4001 frame-relative fix-up, frame ignored near location in segment name Explanation: A fixup occurred with a frame segment different from the target segment where either the frame or the target segment is not absolute. Such a fix-up is meaningless in the OS/2* environment, so the target segment is assumed for the frame segment. Action: Check that this is acceptable. L4002 frame-relative absolute fix-up near location in segment name Explanation: A fixup occurred with a frame segment different from the target segment where both frame and target segments are absolute. This fixup is processed using base-offset arithmetic, but the warning is issued because the fixup might not be valid in the OS/2 environment. Action: Check that this is acceptable. L4003 intersegment self-relative fix up at location in segment name Explanation: LINK386 found an intersegment self-relative fix-up at the specified location. This might cause a problem with the executable file. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4004 possible fix-up overflow at location in segment name Explanation: LINK386 found a possible fix-up overflow at the specified location. This might cause a problem with the executable file. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4005 32-bit fix-up in 16-bit record ignored at location in segment name Explanation: LINK386 encountered a 32-bit fix-up in a 16-bit record at the specified location. This might cause a problem with the executable file. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4006 illegal 16-bit flat-relative offset fix-up at location in object name Explanation: LINK386 encountered an illegal 16-bit flat relative offset fix-up at the specified location. This might cause a problem with the executable file. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4007 illegal 16-bit flat-relative pointer fix-up at location in object name Explanation: LINK386 encountered an illegal 16-bit flat-relative pointer fix-up at the specified location. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4008 aliased fix-up to non-alias object near location in object name Explanation: LINK386 encountered an aliased fix-up to a non-alias object at the specified location. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4009 illegal target of flat-relative fix-up ignored at number in segment name Explanation: LINK386 encountered an illegal flat-relative fix-up at the specified location. Action: The error might have been caused by the way the program was written or when it was compiled or assembled. L4010 invalid alignment specification; assuming number Explanation: The number following the /ALIGNMENT option is not a power of 2, or is not in numerical form. The maximum alignment value is 4096. Action: If the default alignment of 512 is not acceptable, restart LINK386 using a valid number. L4016 /CODEVIEW disables /EXEPACK Explanation: Under certain circumstances, the options /CODEVIEW and /EXEPACK are mutually exclusive. For this executable, /CO or /DE disables the /EXEP option. Action: Restart LINK386 with only one of these options. L4017 name: unrecognized option name; option ignored Explanation: The option specified is not valid for LINK386. Action: Specify a valid option or remove the unrecognized option and relink. L4018 missing or bad application type; option name ignored Explanation: The /PMTYPE option was specified without an application type or with an invalid application type. Action: Relink with an application type of PM, VIO, or NOVIO. L4020 name: code segment size exceeds 65,500 Explanation: The code segment indicated is larger than 65,500 bytes and might not be reliable. Action: Break the segment into smaller segments and try again. L4021 no stack segment Explanation: The program does not contain a stack segment defined with the STACK combine type. Normally, every .EXE program should have a stack segment with the combine type specified as STACK. Action: You can ignore this message if you have a specific reason for not defining a stack or for defining one without the STACK combine type. L4022 name1, name2: groups overlap Explanation: Two groups are defined in such a way that one starts in the middle of another. This can occur if you defined segments in a module definition file or assembly file and did not correctly order the segments by class. Action: Edit the source file and reorder the segments in the group. L4023 name (alias): export internal name conflict Explanation: An exported name, or its associated internal name, conflicts with an already defined public symbol. Action: Edit the source file using new names. L4024 name: multiple definitions for export name Explanation: The module named has been exported more than once with different internal names. All internal names except the first one are ignored. Action: Edit the source file using new names. L4025 modname impname (intname): import internal name conflict Explanation: An imported name, or its associated internal name, is also defined as an exported name. The import name is ignored. The conflict could come from a definition in either the module definition file or an object file. Action: Edit the source file or module definition file using new names. L4026 modname impname (intname): self-imported Explanation: The module definition file directed that a name be imported from the module being produced. Action: Edit the module definition file. L4027 name: multiple definitions for import internal name Explanation: An imported name, or its associated internal name, is imported more than once. The imported name is ignored after the first mention. Action: Check that the name has been defined correctly. L4028 name: segment already defined Explanation: A segment is defined more than once with the same name in the module definition file. Segments must have unique names for LINK386. All definitions with the same name are ignored after the first mention. Action: Check that the segment has been defined correctly. L4029 name: DGROUP segment converted to type data Explanation: A segment that is a member of DGROUP has been defined as type CODE in a module definition file or object file. This probably happened because a CLASS keyword in a SEGMENTS statement was not given. Action: Check the module definition file syntax. L4030 name: segment attributes changed to conform with automatic data segment Explanation: The segment named is defined in DGROUP, but the shared attribute is in conflict with the instance attribute. Example: The shared attribute is NONSHARED and the instance attribute is SINGLE, or the shared attribute is SHARED and the instance attribute is MULTIPLE. The bad segment is forced to have the right shared attribute and the link continues. Action: Check that the LINK386 action is acceptable. L4031 name: segment declared in more than one group Explanation: A segment is declared to be a member of two different groups. Action: Correct the source file and re-create the object files. L4032 name: code-group size exceeds 65500 bytes Explanation: The code group indicated is larger than 65500 bytes and therefore might not be reliable. Action: Break the group into smaller groups or remove one or more segments and try again. L4036 no automatic data segment Explanation: The program or dynamic link library did not define a group named DGROUP. This is recognized by LINK386 as the automatic data segment. Action: Edit the source file. L4038 program has no starting address Explanation: The program did not contain a starting address. Action: Recompile the program and try again. L4044 CODE segment :name in DATA group:name; assuming DATA Explanation: A CODE statement in a module definition file was used to define default attributes for a DATA segment. Action: Define a CODE statement and relink. L4045 name of output file is name Explanation: A dynamic link library file was created without specifying an extension. In such cases, LINK386 supplies an extension of .DLL. This is to warn you in case you expected an .EXE file to be generated Action: No action. L4046 DATA segment: name in CODE group: name; assuming CODE Explanation: A DATA statement in a module definition file was used to define default attributes for a CODE segment. Action: Define a DATA statement and relink. L4048 ignoring non-zero heap size Explanation: The module definition file does not contain a HEAPSIZE statement. Action: Edit the file and relink. L4049 ignoring non-zero stack size Explanation: The module definition file does not contain a STACKSIZE statement. Action: Edit the file and relink. L4051 filename: cannot find library Explanation: LINK386 could not find the specified library file. Action: Enter a new file name, a new path specification, or both. L4053 VM.TMP :illegal file name; ignored Explanation: VM.TMP cannot be used for an object file name. Action: Rename the file and restart LINK386. L4054 filename: cannot find file Explanation: LINK386 could not find the specified file. Action: Enter a new file name, a new path specification, or both. L4067 changing default resolution for weak external name from oldname to newname Explanation: LINK386 encountered a redefinition of a default resolution and is changing it to the value indicated. Action: If the change is OK, no action is required; otherwise, fix the module definition file and try again. L4068 ignoring stack size greater than 64K Explanation: LINK386 encountered a stack greater than 64K or zero and is assuming a stack size of 65,534. Action: Edit the file and relink. L4069 filename truncated to name Explanation: LINK386 encountered a file name greater than 256 bytes (including terminating null) and truncated it to the size indicated. Action: Edit the file and relink. L4071 application type not specified; assuming name Explanation: An application type of WINDOWAPI, WINDOWCOMPAT, NOTWINDOWCOMPAT, or PRIVATE was not specified. LINK386 is assuming the application type indicated. Action: Edit the file and relink. L4072 changing application type from oldname to newname Explanation: The application type specified with /PMTYPE is different from that in .DEF file. LINK386 is using the application type indicated. Action: Edit the file and relink. L4073 name: 32-bit aliased data segment size exceeds 64K Explanation: The segment indicated is greater than 64K in length and is a 32-bit aliased data segment Action: If this is expected, do nothing; if not, break into smaller segments. L4074 attribute conflict for segment name; ignoring attribute type Explanation: The segment indicated for the .DEF file is defined with conflicting characteristics. LINK386 is ignoring the attribute indicated. Action: Edit the file and relink. L4075 object type conflict - assuming name Explanation: The .DEF files specified conflicting attributes for an object; only one of the following attributes are allowed: RESIDENT, NONPERMANENT, PERMANENT, CONTIGUOUS, or DYNAMIC. LINK386 is assuming the attribute indicated. Action: Edit the file and relink. L4077 symbol name not defined; ordered allocation ignored Explanation: While doing ordered allocation of COMDAT records, LINK386 encountered an undefined COMDAT record; ordered allocation is determined from the .DEF file. Action: Edit the file and relink. L4079 symbol name already defined for ordered allocation; duplicate ignored Explanation: While processing ORDER list in .DEF file, LINK386 encountered a COMDAT record already defined for ordered allocation. Action: Edit the file and relink. L4080 changing substitute name for alias name from name to name Explanation: LINK386 encountered an alias redefiniton and is changing it to the values indicated. Action: If this is OK, no action is required. Otherwise, edit the file and relink. L4082 name ignored for module with 16-bit starting address Explanation: LINK386 encountered a DLL module with a 16-bit entry point requesting termination. Only modules with 32-bit entry points can specify DLL termination. Action: Remove the termination request from the module definition file. L4083 invalid base address specification; assuming number Explanation: The base address specified with the /BASE option or in the module definition file is illegal, and LINK386 is assuming the given value. Action: Change the base address if necessary; otherwise, ignore the message. L4084 module name truncated to string Explanation: The module name was truncated to the number of characters indicated. Action: If this action is satisfactory, no action is required. Otherwise, edit the module definition file and shorten the name. L4085 name (alias alias name): forwarder entry created for imported export Explanation: LINK386 created a forwarder entry within the entry table for the named export. Action If this action is satisfactory, no action is required. L4087 internal fix-up applied to uninitialized area at offset in object number Explanation: LINK386 attempted to apply an internal fix-up beyond the initialize limits of the object. Action: If this is acceptable, no action is required. If the problem continues, you might want to disable based addressing. L4090 cannot load identifier manipulation DLL name Explanation: LINK386 detected an error while trying to load an identifier manipulator dynamic link library. This DLL was specified in an object file, and is used by LINK386 to demangle a compiler generated mangled name into a function prototype when printing an error message. Error messages will not be demangled for this object file. Action: Make sure the appropriate identifier manipulator DLL is in the LIBPATH L4091 cannot locate procedure in identifier manipulation DLL name Explanation: LINK386 detected an error while trying to load a procedure from an identifier manipulator dynamic link library. This DLL was specified in an object file, and is used by LINK386 to demangle a compiler generated mangled name into a function prototype when printing an error message. Error messages will not be demangled for this object file. Action: Make sure the appropriate identifier manipulator DLL is in the LIBPATH L4092 too many identifier manipulation DLLs Explanation: Too many identifier manipulator dynamic link libraries have been specified. These DLL's are specified in object files, and are used by LINK386 to demangle compiler generated mangled names into function prototypes when printing an error messages. Error messages may not be demangled for some object files. Action: Reduce the number of different compilers used to create the objects. L4093 cannot initialize identifier manipulation DLL name Explanation: LINK386 detected an error while trying to initialize an identifier manipulator dynamic link library. This DLL was specified in an object file, and is used by LINK386 to demangle a compiler generated mangled name into a function prototype when printing an error message. Error messages will not be demangled for this object file. Action: Make sure the appropriate identifier manipulator DLL is in the LIBPATH. L4094 increasing stack size from number to number Explanation: The stack size specified by either 1. size of a segment with combine type stack 2. STACKSIZE statement in the .DEF file 3. /STACK LINK386 command line option will cause a system error if the program is executed on an OS/2 2.0 system. LINK386 has changed the stacksize to a larger value to preserve compatibility. Action: No action required, LINK386 has corrected the problem. To eliminate the warning message, restart LINK386 and specify the new stack size. ΓòÉΓòÉΓòÉ <hidden> Conditions That Can Cause LINK386 Error 2002 ΓòÉΓòÉΓòÉ LINK386 Error 2002 can be caused by the following conditions: o A group is larger than 64K. o The program contains an intersegment short jump or intersegment short call. o The name of a data item in the program conflicts with that of a subroutine in a library included in the link. o An EXTRN declaration in an assembler language source file appeared inside the body of a segment, as in the following example: code SEGMENT public 'CODE' EXTRN main:far start PROC far call main ret start ENDP code ENDS The following construction is preferred: EXTRN main:far code SEGMENT public 'CODE' start PROC far call main ret start ENDP code ENDS ΓòÉΓòÉΓòÉ 10. MAPSYM ΓòÉΓòÉΓòÉ Select One: Introduction Help Options ΓòÉΓòÉΓòÉ <hidden> MAPSYM - Introduction ΓòÉΓòÉΓòÉ MAPSYM program creates .SYM files from .MAP files. SYM files are used by the kernel debugger for symbolic debugging. Note: You must run MAPSYM from the directory in which the file to be converted is located. To create a .SYM file, follow these steps: 1. Make sure you are in the correct directory. 2. At the prompt type the following: mapsym filename Note that the .MAP extension is not required. ΓòÉΓòÉΓòÉ <hidden> MAPSYM - Help ΓòÉΓòÉΓòÉ To display MAPSYM help, type MAPSYM at the prompt, with no arguments. The appropriate copyright statement appears, along with the following: usage: mapsym [-aln] mapfile ΓòÉΓòÉΓòÉ <hidden> MAPSYM - Options ΓòÉΓòÉΓòÉ The following options may be used with MAPSYM: /A Omits Alphabetical sorting of symbols. /N Includes source code line Numbers in *.SYM file. /L Produces verbose Listing. ΓòÉΓòÉΓòÉ 11. MSGBIND ΓòÉΓòÉΓòÉ ΓòÉΓòÉΓòÉ <hidden> Topics ΓòÉΓòÉΓòÉ Select One: . Introduction Syntax Help Input File Example Multiple Code-Page Message Files Message Retrieval Error Messages ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Syntax ΓòÉΓòÉΓòÉ The MSGBIND command line has the following form: MSGBIND infile The infile field specifies the input file that identifies the executable files, output message files, and message numbers that will be bound. The input-file name can be any valid OS/2* file name and can include an optional file name extension. ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Introduction ΓòÉΓòÉΓòÉ The MSGBIND program binds a message segment to an executable program. It does this by reading an input file that specifies the executable files to modify. For each executable file, MSGBIND specifies which message files to scan, and for each message file, it specifies which messages to include in the executable file. Although the resulting executable file will be larger, access to messages will be faster. In the OS/2* operating system, message segment/objects are packed with other application code. If the size of the code segment/object and the bound messages exceeds 64KB, the following statement in the program definition file (.DEF) isolates the application code from the message statement/object: 16 Bit Applications SEGMENT '_MSGSEG' CLASS 'CODE' 32 Bit Applications SEGMENT '_MSGSEG32' CLASS 'CODE' ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Input File ΓòÉΓòÉΓòÉ The input file contains the following three types of lines: o > Executable file o < Message file o Message numbers. Executable file The File in which messages are to be bound is preceded by a greater-than symbol (>). The name of the file can be any valid OS/2* file name. Two or more different executable files can be modified by the specifications found in one input file. MSGBIND continues to use this file until it encounters another greater-than symbol. Message file The message file to be read from is preceded by a less-than sign (<). You create this file by using the MKMSGF program. The name can be any valid OS/2* file name. All message numbers that follow it are located in the specified message file and are copied to the current output executable file. MSGBIND reads the message-number list until it encounters one of the following: the end of the input file, a new output specification, or a new input message file. Message Numbers The messages in the message file are listed below the message-file name. Only those message numbers that you specify will be added. You can also specify an asterisk (*) to indicate that all messages within the message file will be added. Message numbers must consist of a three-letter component identifier followed by a four-digit message number. See MKMSGF - Input File for a more detailed description of message numbers. ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Multiple Code-Page Message Files ΓòÉΓòÉΓòÉ Multiple code-page message files can also be bound to an executable file, which enables a user to bind to an application messages for different countries. The following example shows how three messages in two different languages can be bound to an executable file: MSGBIND infile where infile consists of the following: >PROG1.EXE <TEXTUS.MSG MSG0001 MSG0002 MSG0003 <TEXTIT.MSG MSG0001 MSG0002 MSG0003 where: o PROG1.EXE is the executable file to be modified. o TEXTUS.MSG is the file, created using MKMSGF, which contains messages in US English. o TEXTIT.MSG is the file, created using MKMSGF, which contains the same messages translated into Italian. o MSGnnnn defines the messages to be bound to the application: MSG Message component ID 0001 Message number ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Help ΓòÉΓòÉΓòÉ To display MSGBIND help, type MSGBIND at the prompt, with no parameters. The following will be displayed: usage: MSGBIND scriptfile ΓòÉΓòÉΓòÉ <hidden> MSGBIND & MKMSGF - How Message Retrieval Works ΓòÉΓòÉΓòÉ When an application requests the message retriever for text associated with a message number, a test is made to determine if there is a bound message segment with this executable file. If true, each bound message segment is searched for a match with the current session's code-page number. If a match is made, then the message number is searched for. If it is found, the message will be returned to the caller. Otherwise, the search of remaining bound message segments will continue. If no match results from a search of all message segments, the message file on the disk is searched. DosGetMessage will access the message file under any of the following conditions: o The message file is in the current directory. o The message file is in the path specified in the DPATH environment variable (protect mode). o The message file is in the path specified in the APPEND environment variable (real mode). o The fully-qualified file name is specified in DosGetMessage. ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Sample Input File ΓòÉΓòÉΓòÉ >c:\cmd.exe <c:\os20\dosutil.msg DOS0100 DOS0123 DOS0245 >c:\format.exe <c:\os20\dosutil.msg DOS0001 DOS0006 <c:\format.msg FMT0001 FMT0002 <c:\myown.msg * The first line of a MSGBIND input file specifies that the executable file to modify is CMD.EXE. The messages DOS0100, DOS0123, and DOS0245 are read from the file DOSUTIL.MSG and added to the CMD.EXE file. The MSGBIND program then encounters an executable-file option for the FORMAT.EXE file. The messages DOS0001 and DOS0006 are read from DOSUTIL.MSG and added to FORMAT.EXE. Next, the messages FMT0001 and FMT0002 are read from the file FORMAT.MSG and added to FORMAT.EXE. Finally, because an asterisk is specified, all the messages are read from the file MYOWN.MSG and added to FORMAT.EXE. The files DOSUTIL.MSG and FORMAT.MSG in this example are two output-message-file names from the MKMSGF program. ΓòÉΓòÉΓòÉ <hidden> MSGBIND - Error Messages ΓòÉΓòÉΓòÉ usage: MSGBIND scriptfile Explanation: The command was entered incorrectly. Action: Restart MSGBIND. Refer to MSGBIND Syntax for the correct syntax. Reading messages from xxxxxxxx Explanation: Messages from the displayed message file are being read into memory. Action: None. This message is for information only. Reading messages from xxxxxxxx -file not found Explanation: The message file was not found in the path specified in the input file. Action: Edit the input file, correcting the path or file name, or both. Restart MSGBIND. Reading messages from xxxxxxxx -not created with MKMSGF program Explanation: The message file displayed was not created using the MKMSGF program. Action: Convert the source message file to a formatted message file using the MKMSGF program, and restart MSGBIND. See the MKMSGF program Reading messages from xxxxxxxx -not enough memory Explanation: There was not enough memory available to store the messages. Action: Reduce the number of programs running in your system, and restart MSGBIND. Updating xxxxxxxx Explanation: The .EXE file name displayed is being updated with the requested messages. Action: None. This message is for information only. Updating xxxxxxxx -file not found Explanation: The .EXE file name was not found in the path specified in the input file. Action: Edit the input file, correcting the path and r file name, or both. Restart MSGBIND. Updating xxxxxxxx -not linked with MSGSEG.OBJ Explanation: The .EXE file name displayed made no DosGetMessage functions, or the .EXE file was not linked with the correct library. Messages can only be bound to applications that call message retriever function, such as DosGetMessage. Action: If the .EXE file does make call message retriever functions, relink the application using the correct library, and restart MSGBIND. Writing messages Explanation: The .EXE file is being updated with the messages requested. Action: None. This message is for information only. MSGBIND: I/O error seeking infile Explanation: A disk error occurred while seeking either the message file or the .EXE file. Action: Run CHKDSK on the drive containing the file and restart MSGBIND. MSGBIND: I/O error writing file Explanation: A disk error occurred while writing messages to the .EXE file. Action: Run CHKDSK on the drive containing the .EXE file, and restart MSGBIND. MSGBIND: Must specify .EXE file before message file Explanation: The input file was in error. Action: Correct input file. MSGBIND: Must specify message file before message number Explanation: The input file was in error. Action: Correct the input file. MSGBIND: Out of memory, needed xxxx bytes Explanation: There was not enough memory available to run MSGBIND. Action: Reduce the number of programs presently running in your system and restart MSGBIND. MSGBIND: Premature EOF during copy Explanation: The .EXE file was not built correctly. Action: Rebuild the .EXE file and restart MSGBIND. MSGBIND: Unable to create temp file-MSGBIND.TMP Explanation: An error occurred while creating the intermediary file MSGBIND.TMP. Action: Delete or move files to make disk space available. If MSGBIND.TMP is present as a read-only file, it must first be deleted. Restart MSGBIND. MSGBIND: Unable to open xxxxxxxx Explanation: The input file specified was not found or an error occurred when opening the message file. Action: Restart MSGBIND using the correct input file name or a backup copy of the message file. WARNING: Skipping messages for this file Explanation: The .EXE file was in error, so the messages were not bound to it. Either the .EXE file does not exist, or it has not been linked with the correct library. Action: If the .EXE file name is correct, relink the application using the correct library, and restart MSGBIND. WARNING: Skipping message numbers for this file Explanation: The message file was in error, so all messages from this message file were ignored. The message file may not exist, may not be formatted correctly, or there may not be enough memory to store all the messages. Action: If the message file name is correct and has been correctly formatted, check the memory available for the file. Restart MSGBIND. WARNING: xxxx is an invalid message number Explanation: The message number specified was not found in the message file. Action: Edit the input file and correct any message numbers that are in error. Restart MSGBIND. Number of Message Files exceeded. Only nnn allowed Explanation: The number of message files specified in the input file exceeds the maximum number of files that MSGBIND can process at one time. Action: Correct the input file or combine message files then restart MSGBIND. The object that would contain the bound messages would be too large. Refer to the Toolkit Documentation for more information. Explanation: (self explanatory) Action: Do one, or more, of the following: 1. Modify the module definition file to isolate the message object then relink the application. 2. Reduce the number of messages to be bound to the application as specified in the input file. 3. Reduce the size of the messages and rebuild the message file with MKMSGF. Then restart MSGBIND. Unable to bind message nnnn, message segment would exceed 64K. The remaining messages will NOT be bound. Explanation: (self explanatory) Action: Do one, or more, of the following: 1. Modify the module definition file to isolate the message object then relink the application. 2. Reduce the number of messages to be bound to the application as specified in the input file. 3. Reduce the size of the messages and rebuild the message file with MKMSGF. Then restart MSGBIND. Unable to locate call to Dos32GetMessage, messages will not be bound. Explanation: The executable file to be modified makes no function calls to the message retriever, or was not linked with the correct library file. Action: If the application does use the message retriever function, such as DosGetMessage, relink the application using the correct library file then restart MSGBIND. If not, messages cannot be bound to the application. Warning: No msgseg data found in new executable Explanation: The executable file to be modified makes no function calls to the message retriever, or was not linked with the correct library file. Action: If the application does use the message retriever function, such as DosGetMessage, relink the application using the correct library file then restart MSGBIND. If not, messages cannot be bound to the application. ΓòÉΓòÉΓòÉ 12. MKMSGF ΓòÉΓòÉΓòÉ ΓòÉΓòÉΓòÉ <hidden> Topics ΓòÉΓòÉΓòÉ Select one: Introduction Syntax Help Input File Example Output File Options Control Files Message Retrieval Error Messages ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Introduction ΓòÉΓòÉΓòÉ The MKMSGF program reads the input message file that you specify and creates an output message file that DosGetMessage uses to display messages. There are two ways that the output message file can be used: o Selected messages can be bound to the message segment of an executable file using the MSGBIND program. o Messages can be accessed directly from the output message file. See How Message Retrieval Works for additional information. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Syntax ΓòÉΓòÉΓòÉ MKMSGF infile outfile [options] OR MKMSGF @controlfile The infile field specifies the input file that contains message definitions. The input-file name can be any valid OS/2* file name, optionally preceded by a drive letter and a path. The outfile field specifies the output file created by MKMSGF. The output-file name can be any valid OS/2* file name, optionally preceded by a drive letter and a path. To differentiate between the two files, the following convention is recommended, using the same file name. o The infile file should have a .TXT extension. o The outfile file should have a .MSG extension. Note: The output file cannot have the same file name and extension as the input file. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Help ΓòÉΓòÉΓòÉ There are two ways to display MKMSGF help. Short Syntax Help To display a short version of MKMSGF syntax help, type MKMSGF at the prompt, with no parameters. The following will be displayed: MKMSGF infile[.ext] outfile[.ext] [/V] [/D <DBCS range or country>] [/P <code page>] [/L <language id,sub id>] Long Help To display a longer version of MKMSGF help, including defaults, country codes, and language IDs, type MKMSGF /? at the prompt. The following will be displayed: Use MKMSGF as follows: MKMSGF <inputfile> <outputfile> [/V] [/D <DBCS range or country>] [/P <code page>] [/L <language family id,sub id>] where the default values are: code page - none DBCS range - none A valid DBCS range is: n10,n11,n20,n21,...,nn0,nn1 A single number is taken as a DBCS country code. The valid OS/2 language/sublanguage ID values are: Code Fam Sub Language Principal country ARA 1 2 Arabic Arab Countries BGR 2 1 Bulgarian Bulgaria CAT 3 1 Catalan Spain CHT 4 1 Traditional Chinese R.O.C. CHS 4 2 Simplified Chinese P.R.C. CSY 5 1 Czech Czechoslovakia DAN 6 1 Danish Denmark DEU 7 1 German Germany DES 7 2 Swiss German Switzerland EEL 8 1 Greek Greece ENU 9 1 US English United States ENG 9 2 UK English United Kingdom ESP 10 1 Castilian Spanish Spain ESM 10 2 Mexican Spanish Mexico FIN 11 1 Finnish Finland FRA 12 1 French France FRB 12 2 Belgian French Belgium FRC 12 3 Canadian French Canada FRS 12 4 Swiss French Switzerland HEB 13 1 Hebrew Israel HUN 14 1 Hungarian Hungary ISL 15 1 Icelandic Iceland ITA 16 1 Italian Italy ITS 16 2 Swiss Italian Switzerland JPN 17 1 Japanese Japan KOR 18 1 Korean Korea NLD 19 1 Dutch Netherlands NLB 19 2 Belgian Dutch Belgium NOR 20 1 Norwegian - Bokmal Norway NON 20 2 Norwegian - Nynorsk Norway PLK 21 1 Polish Poland PTB 22 1 Brazilian Portugues Brazil PTG 22 2 Portuguese Portugal RMS 23 1 Rhaeto-Romanic Switzerland ROM 24 1 Romanian Romania RUS 25 1 Russian U.S.S.R. SHL 26 1 Croato-Serbian (Lat Yugoslavia SHC 26 2 Serbo-Croatian (Cyr Yugoslavia SKY 27 1 Slovakian Czechoslovakia SQI 28 1 Albanian Albania SVE 29 1 Swedish Sweden THA 30 1 Thai Thailand TRK 31 1 Turkish Turkey URD 32 1 Urdu Pakistan BAH 33 1 Bahasa Indonesia ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Input Message File ΓòÉΓòÉΓòÉ The input message file is a standard ASCII file that contains three types of lines: o Comment lines o Component identifier line o Component message lines Comment Lines Comment lines are allowed anywhere in the input message file, except between the component identifier and the first message. Comment lines must begin with a semicolon (;) in the first column. In the Input Message File Example, the comment lines are ; This is a sample of an input ; message file for component DOS ; starting with three comment lines. Component Identifier Line The component-identifier line contains a three-character name identifier that precedes all MKMSGF message numbers. In the example, the component identifier is DOS. Component-Message Lines Each component-message line consists of a message header and an ASCII text message. The message header is comprised of the following parts: o A three-character component identifier o A four-digit message number o A single character specifying message type (E, H, I, P, W, ?) o A colon (:) o Followed by a blank space. The following message types are used: Type Meaning E Error H Help I Information P Prompt W Warning ? no message assigned to this number The message header must begin in the first column of the line. Only one header can precede the text of a message, although a message can span multiple lines. Message numbers can start at any number, but messages must be numbered sequentially. If you do not use a message number, you must insert an empty entry in its place in the text file. An empty entry consists of the message number, with ? as the message type, and no text. The character % has a special meaning when used within the text of a message: %0 is placed at the end of a prompt (type P) to prevent DosGetMessage from executing a carriage return and line feed. This allows the user to be prompted for input on the same line as the message text. %1 - %9 are used to identify variable string insertion within the text of a message. These variables correspond to the Itable and IvCount parameters in the DosGetMessage call. Component-Message Example For example, DOS0100E: is DOS error message 100. For additional examples, see the Input Message File Example. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Output File ΓòÉΓòÉΓòÉ The output file contains the indexed message file that DosGetMessage will use. The output-file name can be any valid OS/2* file name, optionally preceded by a drive letter and a path. The output file cannot have the same name as the input file. To differentiate between the two files, the following convention is recommended, using the same file name. o The infile file should have a .TXT extension. o The outfile file should have a .MSG extension. Help-message file names begin with the component identifier, followed by H.MSG. For example, the help file associated with the component identifier DOS would be DOSH.MSG. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Options ΓòÉΓòÉΓòÉ Text-based messages in different code pages can be created using MKMSGF to display errors, help information, prompt, or provide general information to the application user. MKMSGF uses the following parameter formats to build message files: MKMSGF infile outfile /Pcodepage MKMSGF infile outfile /Ddbcsrange or country id MKMSGF infile outfile /LlangID,VerId MKMSGF infile outfile /V MKMSGF infile outfile /? MKMSGF @controlfile o Infile is the ASCII-text source file. Example: MSG MSG0001I: (mm%4dd%4yy) %2%4%1%4%3 MSG0002I: (dd%4mm%4yy) %1%4%2%4%3 MSG0003I: Current date is: %0 %0 is a special argument that displays a prompt for user input. %1 - %9 are the arguments the user can use to insert text in a message. o Outfile is the binary output message file. o @controlfile is the message definition file. Options /P Code-page ID for the input message file. /D DbcsRange or country ID for the input message file. /L Language family ID (one word) and language version ID (one word). /V Verbose display of message file control variables as the message file is being created. See Verbose Option Output Example. /? Help display of command syntax for MKMSGF. Note: Any combination of /P, /D, /L, and /V switches can be used for either the command line or @controlfile execution method. The / switch prefix and the - prefix can be used interchangeably when defining switches to MKMSGF. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - /Verbose Option Output Example ΓòÉΓòÉΓòÉ Following is a sample of MKMSGF output, using the Verbose option (/V). This output was produced using the following command: mkmsgf myapp.txt myapp.msg /v strIn = myapp.txt strOut = myapp.msg StrIncDir = (null) CodePages = 437 Language family id = 0 and sub id = 0 Language family id and sub id = unspecified flags = none CP_type = SBCS "myapp.txt": length = 382 bytes. 29 messages scanned. Writing output file... Size of table entry: word ΓòÉΓòÉΓòÉ <hidden> MKMSGF - /P Option ΓòÉΓòÉΓòÉ The Code-page option (/P) specifies the code-page ID for that input message file. Up to 16 /P combinations can be saved with the message file. /P cannot be used to identify DBCS data. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - /D Option ΓòÉΓòÉΓòÉ The DBCS option (/D) specifies the DBCSRange or country ID for that input message file. Valid DBCS country ID will cause the initialization of valid DBCS ranges to be set up for this file. For additional information about dbcs, see Double-Byte Character Set. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - /L Option ΓòÉΓòÉΓòÉ The Language option (/L) specifies the language family ID (one word) and language version ID (one word). Valid combination of language family and language version will be set for this file. A valid language family with invalid or undefined language version id will cause a default value of 1 to be set for language version. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Control Files ΓòÉΓòÉΓòÉ The control file (@controlfile) is used to create multiple-code-page message files. The at sign (@) is not part of the file name, but rather, a delimiter required before a control-file name. The control file has the following format: Example: root.in root.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId sub.001 sub1.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId . . sub.00n subn.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId The help option (/?) is invalid due to the purpose of the definition file. Note: Any combination of /P /D /L and /V switches can be used for either the command line or msg_definition_file execution method. ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Input Message File Example ΓòÉΓòÉΓòÉ Following is an example of an input message file: ; This is a sample of an input ; message file for component MAB ; starting with three comment lines. MAB MAB0100E: File not found MAB0101?: MAB0102H: Usage: del [drive:][path] filename MAB0103?: MAB0104I: %1 files copied MAB0105W: Warning! All data will be destroyed! MAB0106?: MAB0107?: MAB0108P: Do you wish to apply these patches (Y or N)? %0 MAB0109E: Divide overflow ΓòÉΓòÉΓòÉ <hidden> MKMSGF - Error Messages ΓòÉΓòÉΓòÉ MKMSGF: Error writing output file Explanation: Error during output to target file. Action: Make sure there is sufficient disk space or that the drive is ready. Retry the command. MKMSGF: Error reading input file Explanation: Error during input from source file. Action: Make sure the source message file exists and that the drive is ready. Retry the command. MKMSGF: File not found Explanation: Input file could not be found Action: Retry the command, using the correct source message file name. MKMSGF: Insufficient storage Explanation: Not enough storage to execute program or too many messages in the file. Message limit is about 6000. Action: Reduce the number of programs running in your system. Or reduce the size of the message file by either deleting messages or by having shorter messages. Retry the command. MKMSGF: Invalid message file format Explanation: Input file is not a recognizable message text file. Action: If an incorrect file name was entered, retry the command with the correct source message file name. MKMSGF: Message ID out of sequence Explanation: A message was detected that was out of the required sequential order. Action: Correct the error by editing your source message file and renumbering the messages. You may also want to delete or insert the appropriate message numbers to achieve the required sequential order. MKMSGF: Message XXXX too long Explanation: The message was too long to be processed (limit is approximately 2K characters). Action: Correct the error by editing your source message file and making the message shorter. Then, retry the command. MKMSGF: infile[.ext] outfile[.ext] [/V] [/D <DBCS range or country>] [/P <code page>] [/L <language id,sub id>] Explanation: This is the proper syntax for MKMSGF. It is displayed when no operands are specified on the command line and after some syntax errors. Action: None MKMSGF: Syntax error Explanation: The user entered the command incorrectly. Action: Retry the command using proper syntax. To display the proper syntax, just enter MKMSGF on the command line. MKMSGF: Codepage %s error in numeric conversion Explanation: The code-page ID specified with the /P option is not numeric. The message file is built with a code-page of zero. Action: Retry the command using the correct code-page specification. MKMSGF: Codepage %s is all zeroes Explanation: The code-page ID specified with the /P option is zero. The message file is built with a code-page of zero. Action: Retry the command using the correct code-page specification. MKMSGF: Codepage %s is too large Explanation: The code-page ID specified with the /P option is too large. The message file is built with a code-page of zero. Action: Retry the command using the correct code-page specification. MKMSGF: Country %u is not supported Explanation: The country ID specified in the /D option is not supported. MKMSGF processing is stopped. Action: Retry the command using the correct country code specification. MKMSGF: DBCS code page not found Explanation: No DBCS code page has been found that supports the DBCS Range specified in the /D option. MKMSGF processing is stopped. Action: Retry the command using the correct DBCS ranges or country ID for the input message file. MKMSGF: Input file same as output file Explanation: The input and output file names are the same, processing is stopped. Action: Correct the command line or the controlfile and restart MKMSGF. MKMSGF: Invalid language or sub id Explanation: The language family ID specified in the /L option is not supported. The message file is built with a language family ID of Action: Retry the command using the correct language family ID. MKMSGF: Language family %s error in numeric conversion Explanation: The language family ID specified with the /L option is not numeric. The message file is built with a language family ID of zero. Action: Retry the command using the correct language family ID. MKMSGF: Language family %s is all zeroes Explanation: The language family ID specified with the /L option is zero. The message file is built with a language family ID of zero. Action: Retry the command using the correct language family ID. MKMSGF: Language family %s is too large Explanation: The language family ID specified with the /L option is not supported. The message file is built with a language family ID of zero. Action: Retry the command using the correct language family ID. MKMSGF: More than NN codepages entered Explanation: A maximum of NN code-page ID's may specified for a single message file, Only the first NN will be accepted. Action: Retry the command using the correct code-page specification(s). MKMSGF: No sub id using 1 default Explanation: The language version ID specified in the /L option is either invalid or not supported. The message file is built using the default value shown. Action: Retry the command using the correct language version ID. MKMSGF: Sub id %s error in numeric conversion Explanation: The language version specified with the /L option is not numeric. The message file is built with a default language version. Action: Retry the command using the correct language version ID. ΓòÉΓòÉΓòÉ 13. MARKEXE ΓòÉΓòÉΓòÉ Select one: Introduction Syntax Syntax Definitions Viewing Program Type Setting Program Type ΓòÉΓòÉΓòÉ <hidden> MARKEXE - Introduction ΓòÉΓòÉΓòÉ The MARKEXE program enables you to view and set the program type for an executable file. The program type identifies the OS/2* sessions in which a program can run. Use MARKEXE with the OS/2 Linear Executable Linker (LINK386) or the OS/2 Segmented Executable Linker (LINK) to change or set the program type of programs you have created. You can set DLL initialization and termination and also enable long file name support. When using LINK386, you can set DLL initialization and termination; long file name support is already set. When using LINK, you can set DLL initialization and long file name support. ΓòÉΓòÉΓòÉ <hidden> MARKEXE - Command-Line Syntax ΓòÉΓòÉΓòÉ MARKEXE uses the following syntax: MARKEXE [/?] [FORCE] [NO] [options] filename... Filename is a file name or a list of file names. Global file-name characters (*.EXE) also can be used. For descriptions of the above terms, see Syntax Definitions. If no option is given, DISPLAY is assumed. Typing MARKEXE /? at the command line displays the appropriate copyright statement along with a list of options. DISPLAY - display status of flags DLLINIT - per-process initialization DLLTERM - per-process termination WINDOWAPI - window api (PM application) WINDOWCOMPAT - window compatible application NOTWINDOWCOMPAT - not window compatible application UNSPECIFIED - unspecified application type LFNS - long file name support ΓòÉΓòÉΓòÉ <hidden> MARKEXE - Syntax Definitions ΓòÉΓòÉΓòÉ MARKEXE has the following keywords, options, and program types. You can also specify any number of files to be viewed or marked. KEYWORDS FORCE Marks the executable file with OS/2 as the target operating system even though the file was marked for another operating system. Using FORCE might produce internally inconsistent executable files. NO Sets the command to the opposite condition. This keyword does not apply to the DISPLAY, UNSPECIFIED, or WINDOWAPI options. OPTIONS DISPLAY Displays the application type in a message; does not make any changes. DLLINIT Sets per process initialization for the dynamic link library. (Use with LINK386 only.) DLLTERM Sets per process termination for the dynamic link library. (Use with LINK only.) LFNS Enables support of long file names. (Use with LINK only.) PROGRAM TYPES MARKEXE does not modify the file if the executable file's program type is the same as the requested type. It displays a message instead. WINDOWAPI The application is a Presentation Manager* application and can run in the Presentation Manager session only. WINDOWCOMPAT The application can run in a Presentation Manager window or in an full-screen session. NOTWINDOWCOMPAT The application must run in an OS/2 full-screen session. UNSPECIFIED The application type is not known. By default, the OS/2 operating system will force the program to run in a full-screen session. Note: Specifying an incorrect program type might cause undesirable results when you try to run that program. For example, do not change a WINDOWCOMPAT program to WINDOWAPI. ΓòÉΓòÉΓòÉ <hidden> MARKEXE - Viewing Program Type ΓòÉΓòÉΓòÉ To display the program type of an executable file without changing the file, specify only a file name, omitting an option. MARKEXE filename.exe Example To view the program type of MYPROG.EXE, type the following: MARKEXE myprog.exe MARKEXE displays the type in a message that looks like this: myprog.exe: OS/2 1.x, WINDOWCOMPAT, LFNS ΓòÉΓòÉΓòÉ <hidden> MARKEXE - Setting Program Type ΓòÉΓòÉΓòÉ To set the program type of an executable file, specify one of the program types. More than one executable file can be set to the same program type on a single command line. MARKEXE type filename.exe another.exe Examples To set WINDOWCOMPAT as the program type of MYPROG.EXE, type: MARKEXE WINDOWCOMPAT myprog.exe To set WINDOWAPI as the program type of several executable files, type: MARKEXE WINDOWAPI marion.exe alex.exe ΓòÉΓòÉΓòÉ 14. NMAKE ΓòÉΓòÉΓòÉ ΓòÉΓòÉΓòÉ <hidden> Topics ΓòÉΓòÉΓòÉ Select One: Introduction Help Syntax Running NMAKE Command Line Command-Line Syntax Command Files Options Description Files Using Macros Command Line Macros Directives Inference Rules Pseudotargets Error Messages ΓòÉΓòÉΓòÉ <hidden> NMAKE - Introduction ΓòÉΓòÉΓòÉ The Program Maintenance Utility (NMAKE) automates the process of updating project files. NMAKE compares the modification dates for one set of files (the target files) with those of another set of files (the dependent files). If any dependent files have changed more recently than the target files, NMAKE executes a series of commands to bring the targets up-to-date. Why Use NMAKE? The most common use of NMAKE is to automate the process of updating a project after you make a change to a source file. Large projects tend to have many source files. Often, only a few of your source files need to be compiled when you make a change. You set up a special text file called a "description" file (or "makefile") that tells NMAKE: o Which files depend on others o Which commands, such as compile and link commands, need to be carried out to bring your program up-to-date This use of NMAKE is only one example of its power. By building suitable description files, you can use NMAKE to o Make backups o Configure data files o Run programs when data files are modified ΓòÉΓòÉΓòÉ <hidden> NMAKE - Help ΓòÉΓòÉΓòÉ To display NMAKE help, type NMAKE /? at the prompt. The appropriate copyright statement appears, along with the following: Usage: NMAKE @commandfile NMAKE /help NMAKE [/nologo] [/acdeinpqrst?] [/f makefile] [/x stderrfile] [macrodefs][targets] Where the options stand for /a force All targets to be built /c Cryptic mode; suppress sign-on banner & warning messages /d Display modification dates /e Environment variables override macros in the makefile /i Ignore exit codes of commands invoked /n No execute mode; display commands only /p Print macro definitions & target descriptions /q Query if target is up to date; for use in batch files /r inference Rules from 'tools.ini' to be ignored /s Silent execution of commands /t Touch targets with current date & time /? Help message /help Help message /nologo do not display sign-on banner ΓòÉΓòÉΓòÉ <hidden> NMAKE - Command-Line Syntax ΓòÉΓòÉΓòÉ NMAKE [options] [macrodefinitions] [targets] [/F filename] * Command-Line Syntax Example NMAKE /S "program = flash" SORT.EXE SEARCH.EXE The above example o Invokes NMAKE with the /S option o Defines a macro, assigning the string "flash" to the string "program" o Specifies two targets: SORT.EXE and SEARCH.EXE By default, NMAKE uses the file named MAKEFILE as the description file ΓòÉΓòÉΓòÉ <hidden> NMAKE - Using the Command Line ΓòÉΓòÉΓòÉ Usage Notes o All fields are optional. o NMAKE always looks first in the current directory for a description file called MAKEFILE. If MAKEFILE does not exist, NMAKE uses the <filename> given with the /F (specify description file) option. <options> Specifies options that modify NMAKE's actions. <macrodefinitions> Lists macro definitions for NMAKE to use. Macro definitions that contain spaces must be enclosed by double quotation marks. <targets> Specifies the names of one or more target files to build. If you do not list any targets, NMAKE builds the first target in the description file. /F <filename> Gives the name of the description file where you specify file dependencies and which commands to execute when a file is out-of-date. ΓòÉΓòÉΓòÉ <hidden> Running NMAKE ΓòÉΓòÉΓòÉ Run NMAKE by typing NMAKE on the operating-system command line. Supply input to NMAKE by either of two methods: o Enter the input directly on the command line o Put your input into a command file (a text file also called a response file) and enter the file name on the command line. Press CTRL+C at any time during an NMAKE run to return to the operating system. Note: Under the OS/2 operating system, do not use the ampersand character (&) to combine the NMAKE command with the CD, CHDIR, or SET command. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Using NMAKE Command Files ΓòÉΓòÉΓòÉ A command file is a response file used to extend command-line input to NMAKE. You can split input to NMAKE between the command line and a command file. Use the name of a command file (preceded by @) where you normally type the input information on the command line. Why Use a Command File? Use a command file for o Complex and long commands you type frequently o Strings of command-line arguments, such as macro definitions, that exceed the limit for command-line length Note: A command file is not the same as a description file. Command File Syntax To provide input to NMAKE with a command file, type NMAKE @commandfile In the <commandfile> field, enter the name of a file containing the same information as is normally entered on the command line. NMAKE treats line breaks that occur between arguments as spaces. Macro definitions can span multiple lines if you end each line except the last with a backslash (\). Macro definitions that contain spaces must be enclosed by quotation marks, just as if they were entered directly on the command line. Example The following is a command file called UPDATE: /S "program \ = flash" SORT.EXE SEARCH.EXE You can use this command file by typing the following command: NMAKE @UPDATE This runs NMAKE using: o The /S option o The macro definition "program = flash" o The targets specified as SORT.EXE and SEARCH.EXE o The description file MAKEFILE by default Note that the backslash allows the macro definition to span two lines. ΓòÉΓòÉΓòÉ <hidden> NMAKE Options ΓòÉΓòÉΓòÉ NMAKE Options Example /? /A /C /D /E /F /HELP /I /N /NOLOGO /P /Q /R /S /T /X ΓòÉΓòÉΓòÉ <hidden> NMAKE - Options Summary ΓòÉΓòÉΓòÉ Usage Notes o Option characters are not case sensitive; /I and /i are equivalent. o You can use either a slash or dash before the option characters; -a and /a are equivalent. /? Display Short Help /A Build All Targets /C Suppress Messages /D Display Modification Dates /E Override Environment Variables /F Specify Description File /HELP Display Help /I Ignore Exit Codes /N Display Commands /NOLOGO Suppress Sign-On Banner /P Print Macro and Target Definitions /Q Return Exit Code /R Ignore TOOLS.INI File /S Suppress Command Display /T Change Target Modification Dates /X Produce standard error file ΓòÉΓòÉΓòÉ <hidden> NMAKE - Options Example ΓòÉΓòÉΓòÉ NMAKE /F QUICK.MAK /C F1 F2 The command above causes NMAKE to execute the commands in the description file QUICK.MAK to update the targets F1 and F2. The /C option suppresses the display of nonfatal error messages and warnings. NMAKE /D /N F1 The command above causes NMAKE to display the commands it would execute to update the target F1. The current directory is assumed to contain a file named MAKEFILE. The /D option displays the modification date of each file, and the /N option displays the commands without executing them. ΓòÉΓòÉΓòÉ <hidden> NMAKE - OPTION X (/X) ΓòÉΓòÉΓòÉ Syntax: /X stderrfile This option produces a standard error file. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Build All Targets (/A) ΓòÉΓòÉΓòÉ Syntax: /A This option builds all specified targets even if they are not out-of-date with respect to their dependent files. See Description Files ΓòÉΓòÉΓòÉ <hidden> NMAKE - Suppress Messages (/C0) ΓòÉΓòÉΓòÉ Syntax: /C This option suppresses display of the NMAKE sign-on banner, nonfatal error messages, and warning messages. To suppress the sign-on banner without suppressing other messages, use the /NOLOGO option. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Display Modification Dates (/D) ΓòÉΓòÉΓòÉ Syntax: /D This option displays the modification date of each file when the dates of target and dependent files are checked. See Description Files ΓòÉΓòÉΓòÉ <hidden> NMAKE - Override Environment Variables (/E) ΓòÉΓòÉΓòÉ Syntax: /E This option disables inherited macro redefinition. NMAKE inherits all current environment variables as macros, which can be redefined in a description file. The /E option disables any redefinition - the inherited macro always has the value of the environment variable. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Specify Description File (/F) ΓòÉΓòÉΓòÉ Syntax: /F filename This option specifies <filename> as the name of the description file to use. If a dash (-) is entered instead of a file name, NMAKE reads a description file from the standard input device, typically the keyboard. If a filename is not specified, it defaults to MAKEFILE. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Display Help (/HELP or /?) ΓòÉΓòÉΓòÉ Syntax: /HELP OR /HELP This option displays a brief summary of NMAKE syntax. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Ignore Exit Codes (/I) ΓòÉΓòÉΓòÉ Syntax: /I This option ignores exit codes (also called errorlevel or return codes) returned by programs such as compilers or linkers called by NMAKE. If this option is not specified, NMAKE ends when any program returns a nonzero exit code. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Display Commands (/N) ΓòÉΓòÉΓòÉ Syntax: /N This option causes NMAKE commands to be displayed but not executed. Use the /N option to o Check which targets are out-of-date with respect to their dependents o Debug description files ΓòÉΓòÉΓòÉ <hidden> NMAKE - Suppress Sign-On Banner (/NOLOGO) ΓòÉΓòÉΓòÉ Syntax: /NOLOGO This option suppresses the sign-on banner display when NMAKE is started. If you want to suppress nonfatal error messages and warnings as well, use the suppress messages (/C) option. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Print Macro and Target Definitions (/P) ΓòÉΓòÉΓòÉ Syntax: /P This option writes out all macro definitions and target definitions. Output is sent to standard output (typically the display). ΓòÉΓòÉΓòÉ <hidden> NMAKE - Return Exit Code (/Q) ΓòÉΓòÉΓòÉ Syntax: /Q This option causes NMAKE to return either of the following: o A 0 exit code if all targets built during an NMAKE run are up to date o A nonzero exit code if they are not up to date Use this option to run NMAKE from within a batch file. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ Syntax: /R This option ignores the following: o All inference rules and macros contained in the TOOLS.INI file o All predefined inference rules and macros See Using a TOOLS.INI File ΓòÉΓòÉΓòÉ <hidden> NMAKE - Suppress Command Display (/S) ΓòÉΓòÉΓòÉ Syntax: /S This option suppresses the display of commands as they are executed by NMAKE. It does not suppress the display of messages generated by the commands themselves. The /N command (Display Commands) takes precedence over the /S option. If you use /N and /S together, commands are displayed but not executed. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Change Target Modification Dates (/T) ΓòÉΓòÉΓòÉ Syntax: /T This option changes the modification dates for out-of-date target files to the current date. No commands are executed, and the target file is left unchanged. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Description Files ΓòÉΓòÉΓòÉ NMAKE uses a description file to determine what to do. In its simplest form, a description file tells NMAKE which files depend on others and which commands need to be executed if a file changes. A description file looks like this: targets... : dependents...Γöé command Γöé"ΓöÇΓöÇΓöÇdescription block : Γöé targets... : dependents... command Description File Topics Description Blocks Special Features ΓòÉΓòÉΓòÉ <hidden> NMAKE - Description Blocks ΓòÉΓòÉΓòÉ A dependent relationship between files is defined in a description block. A "description block" indicates the relationship among various parts of the program. It contains commands to bring all components up to date. The description file can contain any number of description blocks. Description File Description Block ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Description Γöé Γöé Γöé Γöé Γöé Block 1 Γöé Γöé Γöé targets... : dependents... Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé command Γöé Γöé Descr Blk 2 Γöé Γöé command Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé command Γöé Γöé : Γöé Γöé Γöé : Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γöé Γöé Descr Blk n Γöé Γöé Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓòÉΓòÉΓòÉ <hidden> NMAKE - Description File Special Features ΓòÉΓòÉΓòÉ o Description files can contain macro definitions and use macros in description blocks. Macros allow easy substitution of one text string for another. o Description files can contain inference rules. Inference rules allow NMAKE to infer which commands to execute based on the file name extensions used for targets and dependents. o You can specify directories for NMAKE to search for dependent files by using the following syntax: targets : {directory1;directory2...}dependents NMAKE searches the current directory first, then <directory1>, <directory2>, and so on. o A command can be placed on the same line as the target and dependent files by using a semicolon (;) as depicted below: targets... : dependents... ; command o A long command can span several lines if each line ends with a backslash ( \ ): command \ continuation of command o The execution of a command can be modified if you precede the command with special characters o If you do not specify a command in a description block, NMAKE looks for an inference rule to build the target. o DOS and OS/2 wild-card characters (* and ?) can be used in description blocks. For example, the following description block compiles all source files with the .C extension: ASTRO.EXE : *.C ICC *.C o NMAKE uses several punctuation characters in its syntax. To use one of these characters as a literal character, place an escape character ( ^ ) in front of it. o Normally a target file can appear in only one description block. A special syntax allows you to use a target in several description blocks. o A special syntax allows you to determine the drive, path, base name, and extension of the first dependent file in a description block. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macros ΓòÉΓòÉΓòÉ Macros provide a convenient way to replace one string with another in the description file. The text is automatically replaced each time NMAKE is run. This feature makes it easy to change text throughout the description file without having to edit every line that uses the text. Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables Using Macros Using a Defined Macro Other Macro Topics Example Why Use Macros? Special Features of Macros Macro Substitutions ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macros Example ΓòÉΓòÉΓòÉ program = FLASH c = LINK options = $(program).EXE : $(program).OBJ $c $(options) $(program).OBJ; The file above defines three macros. The description block executes the following commands: FLASH.EXE : FLASH.OBJ LINK FLASH.OBJ; ΓòÉΓòÉΓòÉ <hidden> NMAKE - Why Use Macros? ΓòÉΓòÉΓòÉ Two Common Uses of Macros o To create a standard description file for several projects. The macro represents the file names in commands. These file names are defined when you run NMAKE. When you switch to a different project, changing the macro changes the file names NMAKE uses throughout the description file. o To control the options that NMAKE passes to the compiler, assembler, or linker. When using a macro to specify the options, you can quickly change the options throughout the description file in one easy step. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macro Special Features ΓòÉΓòÉΓòÉ Macros have the following special features: o When using a macro, you can substitute text in the macro itself. o Several macros have been predefined for special purposes o If a macro is defined more than once, precedence rules govern which definition is used. o You can also put macros into your TOOLS.INI file. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Defining Macros in a Description File ΓòÉΓòÉΓòÉ Before using a macro, you need to define it, either on the NMAKE command line or in your description file. Description file macro definitions look like this: macroname = macrostring Macro names can be any combination of alphanumeric characters and the underscore character ( _ ) and are case sensitive. A macro string can be any string of characters. The first character of the macro name must be the first character on the line. NMAKE ignores any spaces before or after the equal sign ( = ). The macro string can be a null string and can contain embedded spaces. Do not enclose the macro string in quotation marks; quotation marks are used only when you define macros on the command line. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macros on the Command Line ΓòÉΓòÉΓòÉ Before using a macro, you need to define it, either on the NMAKE command line or in your description file. Command-line macro definitions look like this: macroname=macrostring No spaces can surround the equal sign. If you embed spaces, NMAKE might misinterpret your macro. If your macro string contains embedded spaces, enclose it in double quotation marks ( " ) like this: macroname="macro string" or simply enclose the entire macro definition in double quotation marks ( " ) like this: "macroname = macro string" Macro names can be any combination of alphanumeric characters and the underscore character ( _ ), and they are case sensitive. A macro string can be any string of characters or a null string. See Using a Defined Macro ΓòÉΓòÉΓòÉ <hidden> NMAKE - Inherited Macros ΓòÉΓòÉΓòÉ NMAKE inherits all current environment variables as macros. For example, if you have a PATH environment variable defined as PATH = C:\TOOLS\BIN, the string C:\TOOLS\BIN is substituted when you use PATH in the description file. You can redefine inherited macros by including a line such as the example above in a description file. While NMAKE is executing, the macro takes on the redefined definition. When NMAKE terminates, however, the environment variable resumes its original value. The Override Environment Variables (/E) option disables inherited macro redefinition. If you use this option, NMAKE ignores any attempt to redefine an inherited macro. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Using Defined Macros ΓòÉΓòÉΓòÉ After you have defined a macro, you can use it anywhere in your description file with the following syntax: $(macroname) The parentheses are not required if the macro name is only one character long. To use a dollar sign ( $ ) without using a macro, enter two dollar signs ( $$ ), or use the caret ( ^ ) before the dollar sign as an escape character. When NMAKE runs, it replaces all occurrences of $(macroname) with the defined macro string. If the macro is undefined, nothing is substituted. Once a macro is defined, you can cancel it only with the !UNDEF directive. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macro Substitutions ΓòÉΓòÉΓòÉ Just as you use macros to substitute text within a description file, you use the following syntax to substitute text within a macro: $(macroname: string1 = string2) Every occurrence of <string1> is replaced by <string2> in <macroname>. Spaces between the colon and <string1> are considered part of <string1>. If <string2> is a null string, all occurrences of <string1> are deleted from the macro. The colon ( : ) must immediately follow <macroname>. Note: The replacement of <string1> with <string2> in the macro is not a permanent change. If you use the macro again without a substitution, you get the original unchanged macro. Example SOURCES = ONE.C TWO.C THREE.C PROGRAM.EXE : $(SOURCES:.C=.OBJ) LINK $**; The description file above defines a macro called SOURCES, which contains the names of three C source files. With this macro, the target/dependent line substitutes the .OBJ extension for the .C extension. Thus, NMAKE executes the following command: LINK ONE.OBJ TWO.OBJ THREE.OBJ; Note: $** is a special macro that translates to all dependent files for a given target. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Special Macros ΓòÉΓòÉΓòÉ NMAKE predefines several macros. The first six macros below return one or more file specifications for the files in the target/dependent line of a description block. Except where noted, the file specification includes the path of the file, the base file name, and the file-name extension. Macro Value $@ The specification of the target file. $* The base name (without extension or path) of the target file. This macro can not be used in a dependents list. $** The specifications of the dependent files. $? The specifications for only those dependent files that are out-of-date with respect to the targets. $< The specification of a single dependent file that is out-of-date with respect to the targets. This macro is used only in inference rules. $$@ The file specification of the target that NMAKE is currently evaluating. This is a dynamic dependency parameter, used only in dependents lists. $(CC) The string ICC, which is the command to run the C Optimizing Compiler. You can redefine this macro to use a different command. $(AS) The string MASM, which is the command to run the Macro Assembler (MASM). You can redefine this macro to use a different command. $(MAKE) The command name used to run NMAKE. This macro is used to invoke NMAKE recursively. If you redefine this macro, NMAKE issues a warning message. Note: NMAKE executes the command line in which $(MAKE) appears, even if the display commands (/N) option is on. $(MAKEFLAGS) The NMAKE options currently in effect. You cannot redefine this macro. Note: The special macros $** and $$@ are the only exceptions to the rule that macro names longer than one character must be enclosed in parentheses. You can append characters to any of the first six macros in this list to modify the meaning of the macro. However, you cannot use macro substitutions in these macros. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Special Macros Examples ΓòÉΓòÉΓòÉ Special Macros TRIG.LIB : SIN.OBJ COS.OBJ ARCTAN.OBJ !LIB TRIG.LIB -+$?; In the example above, the macro $? represents the names of all dependent files that are out-of-date with respect to the target file. The exclamation point ( ! ) preceding the LIB command causes NMAKE to execute the LIB command once for each dependent file in the list. As a result of this description, the LIB command is executed up to three times, each time replacing a module with a newer version. DIR=C:\INCLUDE $(DIR)\GLOBALS.H : GLOBALS.H COPY GLOBALS.H $@ $(DIR)\TYPES.H : TYPES.H COPY TYPES.H $@ $(DIR)\MACROS.H : MACROS.H COPY MACROS.H $@ The example above shows how to update a group of include files. in the description file above, each of the files GLOBALS.H, TYPES.H, and MACROS.H in the directory C:\INCLUDE depends on its counterpart in the current directory. If one of the include files is out-of-date, NMAKE replaces it with the file of the same name from the current directory. The following description file, which uses the special macro $$@, is equivalent: DIR=C:\INCLUDE $(DIR)\GLOBALS.H $(DIR)\TYPES.H $(DIR)\MACROS.H : $$(@F) !COPY $? $@ The special macro $$(@F) signifies the file name (without the path) of the current target. When NMAKE evaluates the description block, it evaluates the three targets, one at a time, with respect to their dependents. Thus, NMAKE first checks whether C:\INCLUDE\GLOBALS.H is out-of-date compared with GLOBALS.H in the current directory. If so, it executes the command to copy the dependent file GLOBALS.H to the target. NMAKE repeats the procedure for the other two targets. Note that on the command line, the macro $? refers to the dependent for this target. The macro $@ specifies the full file specification of the target file. Other Macro Topics Macros Why Use Macros? Macro Example Special Features of Macros Using a Defined Macro Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables ΓòÉΓòÉΓòÉ <hidden> NMAKE - File-Specification Parts ΓòÉΓòÉΓòÉ A full file specification gives the base name of the file, the file-name extension, and the path. The path provides the disk- drive identifier and the sequence of directories needed to locate the file on the disk. For example, the file specification C:\SOURCE\PROG\SORT.OBJ has the following parts: Path Name C:\SOURCE\PROG Base File Name SORT File-Name Extension .OBJ Other Macro Topics Macros Why Use Macros? Macro Example Special Features of Macros Using a Defined Macro Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables ΓòÉΓòÉΓòÉ <hidden> NMAKE - Characters that Modify Special Macros ΓòÉΓòÉΓòÉ Example The following six macros all resolve to a file specification (or possibly several file specifications for $** and $?): $* $@ $** $< $? $$@ You can append characters to any of these macros to modify the file name returned by the macro. Depending on which character you use, parts of the full file specification are returned: Appended Character File Part Returned D F B R File Path Yes No No Yes Base File Name No Yes Yes Yes File Name Extension No Yes No No Other Macro Topics Macros Why Use Macros? Macro Example Special Features of Macros Using a Defined Macro Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables ΓòÉΓòÉΓòÉ <hidden> NMAKE - Modified Special Macros Example ΓòÉΓòÉΓòÉ Modifying Special Macros If the macro $@ has the value C:\SOURCE\PROG\SORT.OBJ then the following values are returned for the modified macro: Macro Value $(@D) C:\SOURCE\PROG $(@F) SORT.OBJ $(@B) SORT $(@R) C:\SOURCE\PROG\SORT Note: Modified macros are always longer than a single character - they must be enclosed by parentheses when used. Other Macro Topics Macros Why Use Macros? Macro Example Special Features of Macros Using a Defined Macro Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macro Precedence Rules ΓòÉΓòÉΓòÉ When the same macro is defined in more than one place, the definition with the highest priority is used: Priority Definition 1 (Highest) Command line 2 Description file 3 Environment variables 4 TOOLS.INI file 5 (Lowest) Predefined macros (such as CC and AS) If you invoke NMAKE with the Overriding Macro Definitions (/E) option, macros defined by environment variables take precedence over those defined in a description file. Other Macro Topics Macros Why Use Macros? Macro Example Special Features of Macros Using a Defined Macro Defining a Macro In a Description File On the Command Line In TOOLS.INI Inherited from Environment Variables ΓòÉΓòÉΓòÉ <hidden> NMAKE - Inference Rules ΓòÉΓòÉΓòÉ Inference rules are templates from which NMAKE infers what to do with a description block when no commands are given. Only those extensions defined in a .SUFFIXES list can have inference rules. The extensions .C, .OBJ, .ASM, and .EXE are automatically included in .SUFFIXES. When NMAKE encounters a description block with no commands, it looks for an inference rule that specifies how to create the target from the dependent files, given the two file extensions. Similarly, if a dependent file does not exist, NMAKE looks for an inference rule that specifies how to create the dependent from another file with the same base name. NMAKE applies an inference rule only if the base name of the file it is trying to create matches the base name of a file that already exists. In effect, inference rules are useful only when there is a one-to-one correspondence between the files with the "from" extension and the files with the "to" extension. You cannot, for example, define an inference rule that inserts a number of modules into a library. The use of inference rules eliminates the need to put the same commands in several description blocks. For example, you can use inference rules to specify a single ICC command that changes any C source file (with a .C extension) to an object file (with a .OBJ extension). You define an inference rule by including text of the following form in your description file (or in your TOOLS.INI file - see Special Features below): .fromext.toext: commands : The elements of the inference rule are: <fromext> The file name extension for dependent files to build a target <toext> The file name extension for target files to be built <commands> The commands to build the <toext> target from the <fromext> dependents For example, an inference rule to convert C source files (with the .C extension) to C object files (with the .OBJ extension) is .C.OBJ: ICC $<; Note: The special macro $< represents the name of a dependent out-of-date relative to the target. Special Features o You can specify a path where NMAKE should look for target and dependent files used in inference rules. o Inference rules are predefined for compiling and linking C programs, and for assembling programs. o NMAKE looks for inference rules in the TOOLS.INI file if it cannot find a rule in a description file. o Only those extensions defined in a .SUFFIXES list can have inference rules. The extensions .C, .OBJ, .ASM, and .EXE are automatically included in .SUFFIXES. o Description Inference Rules Topics Inference Rules Example Inference-Rule Path Specifications Predefined Inference Rules Description File Special Features Macros and Inference Rules in TOOLS.INI Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ <hidden> NMAKE - Inference Rules Example ΓòÉΓòÉΓòÉ .OBJ.EXE: LINK $<; EXAMPLE1.EXE: EXAMPLE1.OBJ EXAMPLE2.EXE: EXAMPLE2.OBJ LINK /CO EXAMPLE2,,,LIBV3.LIB The first line above defines an inference rule that causes the LINK command to create an executable file whenever a change is made in the corresponding object file. The file name in the inference rule is specified with the special macro $< so that the rule applies to any .OBJ file with an out-of-date executable file. When NMAKE does not find any commands in the first description block, it checks for a rule that may apply and finds the rule defined on the first two lines of the description file. NMAKE applies the rule, replacing $< with EXAMPLE1.OBJ when it executes the command, so that the LINK command becomes LINK EXAMPLE1.OBJ; NMAKE does not search for an inference rule when examining the second description block, because a command is explicitly given. Inference Rules Topics Inference Rules Inference-Rule Path Specifications Predefined Inference Rules Description File Special Features Macros and Inference Rules in TOOLS.INI Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ <hidden> NMAKE - Inference-Rule Path Specifications ΓòÉΓòÉΓòÉ When defining an inference rule, you can indicate to NMAKE where to look for target and dependent files. Use the following syntax: {frompath}.fromext{topath}.toext commands : NMAKE looks in the directory specified by <frompath> for files with the <fromext> extension. It executes the commands to build files with the <toext> extension in the directory specified by <topath>. Inference Rules Topics Inference Rules Inference Rules Example Predefined Inference Rules Description File Special Features Macros and Inference Rules in TOOLS.INI Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ <hidden> NMAKE - Predefined Inference Rules ΓòÉΓòÉΓòÉ NMAKE predefines three inference rules: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöéInferenceΓöéDefault ΓöéCommand Γöé ΓöéRule Γöé ΓöéAction Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé.C.OBJ Γöé$(CC) $(CFLAGS) /C $*.CΓöéICC /C Γöé Γöé Γöé Γöé$*.C Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé.C.EXE Γöé$(CC) $(CFLAGS) $*.C ΓöéICC $*.C Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé.ASM.OBJ Γöé$(AS) $(AFLAGS) $*; ΓöéMASM $*; Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Note: The first two rules automatically compile and link C programs. The last rule automatically assembles programs. Inference Rules Topics Inference Rules Inference Rules Example Inference-Rule Path Specifications Description File Special Features Macros and Inference Rules in TOOLS.INI Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ <hidden> NMAKE - Directives ΓòÉΓòÉΓòÉ Example Using directives, you can construct description files similar to batch files. NMAKE provides directives that o Conditionally execute commands o Display error messages o Include the contents of other files o Turn some NMAKE options on or off Each directive begins with an exclamation point ( ! ) in the first column of the description file. Spaces can be placed between the exclamation point and the directive keyword. The list below describes the directives: !IF <expression> Executes the statements between the !IF keyword and the next !ELSE or !ENDIF directive if <expression> evaluates to a nonzero value. See Expressions in !IF Directives !ELSE Executes the statements between the !ELSE and !ENDIF directives if the statements preceding the !ELSE directive were not executed. !ENDIF Marks the end of the !IF, !IFDEF, or !IFNDEF block of statements. !IFDEF <macroname> Executes the statements between the !IFDEF keyword and the next !ELSE or !ENDIF directive if <macroname> is defined in the description file. If a macro has been defined as null, it is still considered to be defined. !IFNDEF <macroname> Executes the statements between the !IFNDEF keyword and the next !ELSE or !ENDIF directive if <macroname> is not defined in the description file. !UNDEF <macroname> Undefines a previously defined macro. !ERROR <text> Prints text and then stops execution. !INCLUDE <filename> Reads and evaluates the file <filename> before continuing with the current description file. If <filename> is enclosed by angle brackets (<>), NMAKE searches for the file in the directories specified by the INCLUDE macro; otherwise, it looks only in the current directory. The INCLUDE macro is initially set to the value of the INCLUDE environment variable. !CMDSWITCHES {+|-}<opt> Turns on or off one of four NMAKE options: /D, /I, /N, and /S. If no options are specified, the options are reset to the values they had when NMAKE was started. To turn an option on, precede it with a plus sign (+); to turn it off, precede it with a minus sign (-). This directive updates the MAKEFLAGS macro. See Special Macros ΓòÉΓòÉΓòÉ <hidden> NMAKE - Directives Example ΓòÉΓòÉΓòÉ Directives !INCLUDE <INFRULES.TXT> !CMDSWITCHES +D WINNER.EXE:WINNER.OBJ !IFDEF DEBUG ! IF "$(DEBUG)"=="y" LINK /CO WINNER.OBJ; ! ELSE LINK WINNER.OBJ; ! ENDIF !ELSE ! ERROR Macro named DEBUG is not defined. !ENDIF This description file does the following: o The !INCLUDE directive causes the file INFRULES.TXT to be read and evaluated as if it were part of the description file. o The !CMDSWITCHES directive turns on the /D option, which displays the dates of the files as they are checked. o If WINNER.EXE is out-of-date with respect to WINNER.OBJ, the !IFDEF directive checks to see whether the macro DEBUG is defined. If it is defined, the !IF directive checks to see whether it is set to y. If it is, the linker is invoked with the /CO option; otherwise, it is invoked without the /CO. If the DEBUG macro is not defined, the !ERROR directive prints the message and NMAKE stops executing. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Expressions in !IF Directives ΓòÉΓòÉΓòÉ The <expression> used with the !IF directive can consist of integer constants, string constants, or exit codes returned by programs. Integer constants can use the C unary operators for numerical negation (-), one's complement ( ~ ), and logical negation (!). You can also use any of the C binary operators listed below: Operator Description + Addition - Subtraction * Multiplication / Division % Modulus & Bitwise AND | Bitwise OR ^^ Bitwise XOR && Logical AND || Logical OR << Left shift >> Right shift == Equality != Inequality < Less than > Greater than <= Less than or equal to >= Greater than or equal to NOTES o You can use parentheses to group expressions. o Values are assumed to be decimal values unless specified with a leading 0 (octal) or leading 0x (hexadecimal). o Strings are enclosed by quotes ( " ). You can use the equality (==) and inequality (!=) operators to compare two strings. o You can invoke a program in an expression by enclosing the program name in square brackets ( [ ] ). The exit code returned by the program is used in the expression. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Pseudotargets ΓòÉΓòÉΓòÉ A "pseudotarget" is a target in a description block that is not a file. Instead, it is a name that serves as a "handle" for building a group of files or executing a group of commands. In the following example, UPDATE is a pseudotarget: UPDATE: *.* !copy $** A:\PRODUCT When NMAKE evaluates a pseudotarget, it always considers the dependents to be out-of-date. In the description above, NMAKE copies each of the dependent files to the specified drive and directory. NMAKE predefines several pseudotargets for special purposes. See Predefined Pseudotargets ΓòÉΓòÉΓòÉ <hidden> NMAKE - Error Messages ΓòÉΓòÉΓòÉ This section provides a convenient reference to the many error messages that can be encountered when using the NMAKE facility. Error Message Descriptions NMAKE Fatal Error Messages (Part 1) 1000 - 1098 NMAKE Warnings (Part 2) 4001 - 4008 NMAKE Informational Messages (Part 3) 2 - 6 ΓòÉΓòÉΓòÉ <hidden> NMAKE - Fatal Error Messages (Part 1) 1000 - 1098 ΓòÉΓòÉΓòÉ U1000 syntax error : `)' missing in macro invocation Explanation: A left parenthesis appeared without a matching right parenthesis in a macro invocation. The correct form is $(name). Action: Add the right parenthesis in the proper syntax. U1001 syntax error : illegal character `character' in macro Explanation: A non-alphanumeric character other than underscore appeared in a macro. Action: Use only characters valid for a macro name. U1002 syntax error : bad macro invocation `$' Explanation: A single dollar sign ($) appeared without a macro name associated with it. The correct form is $(name). Action: Use a defined macro name. U1003 syntax error : `=' mising in macro Explanation: The = sign was missing in a macro definition. The correct form is `name = value'. Action: Insert an equals sign (=) and retry. U1004 syntax error : macro name missing Explanation: A macro invocation appeared without a name. The correct form is $(name). Action: Supply the macro name and retry. U1005 syntax error : text must follow `:' in macro Explanation: A string substitution was specified for a macro, but the string to be changed in the macro was not specified. Action: Specify the string to be substituted. U1006 syntax error : missing closing double quotation mark Explanation: An opening double quotation mark appeared without a closing quotation mark. Action: Edit the line and add the closing quotation mark. U1007 double quotation mark not allowed in name Explanation: You used a `"' symbol inside a macro name. Action: Correct the name without the quotation mark. U1017 unknown directive `directive' Explanation: The directive specified is not a recognized directive. Action: Check your spelling of the intended directive. U1018 directive and/or expression part missing Explanation: The directive is incompletely specified. The expression part is required. Action: Supply the expression and retry the directive. U1019 too many nested if blocks Explanation: You exceeded the limit of 16 levels of nested !IF directives. Action: Simplify your nesting logic to fewer than 16 levels. U1020 EOF found before next directive Explanation: A directive, such as !ENDIF, was missing. Action: Insert the required directive and retry. U1021 syntax error : else unexpected Explanation: An !ELSE directive was found that was not expected, or was placed in a syntactically incorrect place. Action: Correct the position of the !ELSE directive. U1022 missing terminating character for string/program invocation : `character' Explanation: The closing double quotation mark in a string comparison in an !IF directive was missing. Or else the closing bracket (]) in a program invocation in a directive is missing. Action: Insert the proper termination character. U1023 syntax error present in expression Explanation: An expression is incorrect. Action: Check the allowed operators and operator precedence for the expression. U1024 illegal argument to !CMDSWITCHES Explanation: An unrecognized !CMDSWITCHES option was specified. Action: Use the correct !CMDSWITCHES option. U1031 file name missing (or macro is null) Explanation: An !INCLUDE directive was found, but the name of the file to include is missing. Action: Supply the name of the file to be included. U1033 syntax error : `string' unexpected Explanation: The specified string is not part of the valid syntax for a makefile. Action: Correct the line according to the proper syntax. U1034 syntax error : separator missing Explanation: The colon that separates targets from dependents is missing. Action: Insert a colon after the target list. L1035 syntax error : expected `:' or `=' separator Explanation: Either a colon, implying a dependency line, or an = sign, implying a macro definition, was expected. Action: Insert the proper separator in the line. U1036 syntax error : too many names to left of `=' Explanation: Only one string is allowed to the left of a macro definition. Action: Remove the incorrect text before the = sign. U1037 syntax error : target name missing Explanation: A colon (:) was found before a target name was found. At least one target is required. Action: Insert the correct target name before the colon. U1038 internal error : lexer Explanation: The lexer encountered an unexpected condition. Action: Note the circumstances of the failure and contact IBM Support. U1039 internal error : parser Explanation: The parser encountered an unexpected condition. Action: Note the circumstances of the failure and contact IBM Support. U1040 internal error : macro expansion Explanation: An unexpected condition was found during macro expansion. Action: Note the circumstances of the failure and contact IBM Support. U1041 internal error : target building Explanation: An unexpected condition was found during target building. Action: Note the circumstances of the failure and contact IBM Support. U1042 internal error : expression stack overflow Explanation: An expression was too complex to decode using internal memory space. Action: Note the circumstances of the failure and contact IBM Support. U1043 internal error : temp file limit exceeded Explanation: NMAKE required too many temporary files. Action: Note the circumstances of the failure and contact IBM Support. U1044 internal error : too many levels of recursion building a target Explanation: Recursive invocations of NMAKE exceeded available memory. Action: Note the circumstances of the failure and contact IBM Support. U1045 messagetext Explanation: NMAKE encountered an unexpected condition. Action: Note the text of the message and contact IBM Support. U1046 internal error : out of search handles Explanation: NMAKE exceeded an internal limit on handles. Action: Note the circumstances of the failure and contact IBM Support. U1049 macro too long (max allowed size : 64K) Explanation: One of your macros expanded to longer than 65535 bytes. Action: Recode the macro definition so that it is less than 64K. U1050 user-specified text Explanation: The message specified with the !ERROR directive is displayed. Action: Action depends on the defined error condition. U1051 out of memory Explanation: NMAKE ran out of space in the far heap. Action: Note the circumstances of the failure and contact IBM Support. U1052 file `filename' not found Explanation: The file was not found. Action: Specify the filename properly in the makefile. U1053 file `filename' unreadable Explanation: The filename cannot be read. Action: Be sure that the file has the appropriate attributes to be read. U1054 cannot create in-line file `filename' Explanation: The program was unable to generate the specified in-line file as a uniquely-named temporary file. Action: Be sure your file system has enough space for temporary files. U1055 out of environment space Explanation: The environment space limit was reached. Action: Restart NMAKE with a larger environment space. U1056 cannot find command processor Explanation: The command processor CMD.EXE could not be found. Action: Be sure that the COMSPEC environment variable points to a command processor on your file system. U1057 cannot delete temporary file `filename' Explanation: The program was unable to delete the specified file. Action: The file needs to exist and have the write attribute. U1058 terminated by user Explanation: You pressed Ctrl+Break to stop NMAKE. Action: None, the program has stopped. U1060 unable to close file : `filename' Explanation: NMAKE was unable to close filename. Action: Look for the named file with write attribute on your file system. U1061 /F option requires a file name Explanation: You coded command-line option /f but failed to follow it with the name of a description file. Action: Specify the description file name after the option. U1062 missing file name with /X option Explanation: You coded command-line option /x but failed to follow it with the name of a file to receive redirected stderr output. Action: Give an output error file name after the option. U1063 missing macro name before `=' Explanation: You coded `=' in a command line macro definition, but failed to supply the name of the macro. Action: Give the macro name in the definition. U1064 MAKEFILE not found and no target specified Explanation: You invoked NMAKE without a /f option, and no file named MAKEFILE was present. Action: Either create a file named MAKEFILE, or use the /f switch. U1065 incorrect option `option' Explanation: NMAKE does not use the option which you specified. Action: Use a valid command line option. U1070 cycle in macro definition `macroname' Explanation: A cycle was detected in the macro definition specified. Action: Rewrite the macro to avoid the circular definition. U1071 cycle in dependency tree for target `targetname' Explanation: A cycle was detected in the target dependency tree. Action: Check the dependency lists descending from the given target and remove the circular dependency. U1072 cycle in include files : `filenames' Explanation: A cycle was detected in the tree of included files. Action: Check the file names included by the given include file and remove the circular inclusion. U1073 don't know how to make `filename' Explanation: The specified target does not exist and there are no commands to execute or inference rules given for it. Hence NMAKE cannot build it. Action: Correct the specification of the file, which should exist on your file system. U1076 name too long Explanation: The macro name, target name, or build command name would overflow an internal buffer. Action: Reduce the length of the specified name. U1077 `program' : return code `value' Explanation: The invocation of NMAKE failed with a nonzero return value. Action: Determine the cause of failure of the specified program. U1078 constant overflow at `directive' Explanation: A constant in `directive' expression was too big. Action: Reduce the size of the specified constant to a value within the range of a signed long integer, -2147483648 <= value <= 2147483647. U1079 illegal expression : divide by zero present Explanation: An expression contains a division by zero. Action: Remove the undefined division by zero from the expression. U1080 operator and/or operand out of place : usage illegal Explanation: The expression uses an operand or operator incorrectly. Action: Check the allowed set of operators and their precedence. U1081 `program' : program not found Explanation: NMAKE could not find the external command or program. Action: Be sure that the program is located in the PATH. U1082 `command' : cannot execute command: out of memory Explanation: NMAKE ran out of memory while running command. Action: Make more memory available while running NMAKE. U1083 target macro `macroname' expands to nothing Explanation: The expansion of the given macro is a null string. Action: Correct the definition of the macro. U1084 cannot create temporary file `filename' Explanation: NMAKE was unable to open the specified temporary file. Action: Check the filename specification for validity. U1085 cannot mix implicit and explicit rules Explanation: A regular target was specified along with the target for a rule (which has the form .sufx1.sufx2). Action: Separate targets built by implicit and explicit inference rules into different lists. U1086 inference rule cannot have dependents Explanation: Dependents are not allowed in the definition of an inference rule. Action: Remove the dependents list from the rule. U1087 cannot have : and :: dependents for same target Explanation: A target cannot have both a single-colon and double-colon dependency. Action: Choose either single-colon or double-colon separator for the target. U1088 invalid separator on inference rule : `::' Explanation: Inference rules can use only a single-colon separator. Action: Use a single-colon dependency for the target. U1089 cannot have build commands for pseudotarget `targetname' Explanation: Pseudotargets (for example, .PRECIOUS, .SUFFIXES) cannot have build commands specified. Action: Remove the build commands from the specification of targetname. U1090 cannot have dependents for pseudotarget `targetname' Explanation: The specified pseudotarget, for example, .SILENT, .IGNORE) cannot have a dependent. Action: Remove the dependent from the specification of targetname. U1092 too many names in rule Explanation: The rules cannot have more than one pair of extensions (ext1.ext2) as a target for the rule. Action: Use only one pair of extensions in any inference rule. U1093 cannot mix special pseudotargets Explanation: It is illegal to list two or more pseudotargets together. Action: Use only one pseudotarget in any list. U1094 syntax error : only [no]keep allowed here Explanation: In a context where only KEEP or NOKEEP is accepted to indicate the desired disposition of the inline file, you used an incorrect string. Action: Use the correct syntax for In-Line Files. U1095 expanded command line `string' too long Explanation: After macro expansion, the command line length exceeds 1024 bytes. Action: Rewrite the command line to stay within a 1024-byte limit. U1097 extmake syntax usage error, no dependent Explanation: You used the extmake file syntax on a description block which had no dependent files. Action: Specify one or more dependent files for the block. U1098 extmake syntax in `string' incorrect Explanation: The given string contains an extmake syntax error. Action: Correct the string according to the proper syntax. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Warnings (Part 2) 4001 - 4008 ΓòÉΓòÉΓòÉ U4001 command file can be invoked only from command line Explanation: You used an @ symbol on an argument in a command file. You cannot invoke another command file from within a command file. Action: If the you want `@' to be part of an argument in a command file, you must enclose that argument in quotation marks. U4002 no match found for wild card `string' Explanation: NMAKE expanded wildcards in the given string, but found no files matching the specification. Action: Check the existence of desired files on your file system. U4004 too many rules for target `targetname' Explanation: You specified too many inference rules for the specified targetname. Action: Revise your rules specification for targetname. U4005 ignoring rule `string' (extension not in .SUFFIXES) Explanation: You specified an inference rule with a suffix which was not in the .SUFFIXES list. Action: To use the suffix, be sure to include it in the .SUFFIXES list. U4006 special macro undefined : `macroname' Explanation: You specified the undefined macro macroname. Action: NMAKE will ignore the undefined macroname. You may use only predefined special macros. U4007 file name `filename' too long; truncating to 8.3 Explanation: The specified filename is too long for a FAT file system name. Action: NMAKE will shorten the filename to at most an eight-character name and 3-character extension. U4008 removed target `filename' Explanation: While deleting non-precious files, NMAKE erased the specified filename which was a target. Action: Check your lists of targets and dependent files to be sure that filename is not needed. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Informational Messages (Part 3) 2-6 ΓòÉΓòÉΓòÉ Message 2 `filename' is up-to-date. Explanation: The specified target filename is no older than any of its dependent files. Action: NMAKE does not need to rebuild this target. Message 3 **`file1' newer than `file2' Explanation: While reporting creation times of files, NMAKE notes that file1 was created after file2. Action: [none] Message 5 touch `filename' Explanation: You specified option /t to touch targets with the current date and time. Action: NMAKE has updated the creation time of filename. Message 6 `filename' target does not exist Explanation: The specified filename could not be found. Action: NMAKE will rebuild the target. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Predefined Pseudotargets ΓòÉΓòÉΓòÉ NMAKE predefines several pseudotargets that provide special rules within a description file: .SILENT Suppresses command display .IGNORE Ignores exit codes .SUFFIXES Defines file suffixes .PRECIOUS Preserves target file ΓòÉΓòÉΓòÉ <hidden> NMAKE - .SILENT Pseudotarget ΓòÉΓòÉΓòÉ Syntax: .SILENT : dependents... This pseudotarget suppresses the display of executed commands for a single description block. The /S option does the same thing for all description blocks. See Suppress Command Display (/S) ΓòÉΓòÉΓòÉ <hidden> NMAKE - xxx .IGNORE Pseudotarget ΓòÉΓòÉΓòÉ Syntax: .IGNORE : dependents... This pseudotarget ignores exit codes returned by programs for a single description block. The /I option does the same thing for all description blocks. See Ignore Exit Codes (/I) ΓòÉΓòÉΓòÉ <hidden> NMAKE - .SUFFIXES Pseudotarget ΓòÉΓòÉΓòÉ Syntax: .SUFFIXES : extensions... This pseudotarget defines file extensions to try when NMAKE needs to build a target file for which no dependents are specified. NMAKE searches the current directory for a file with the same name as the target file and an extension in <extensions...>. If NMAKE finds such a file, and if an inference rule applies to the file, NMAKE treats the file as a dependent of the target. The .SUFFIXES pseudotarget is predefined as .SUFFIXES : .OBJ .EXE .C .ASM To add extensions to the list, specify .SUFFIXES : followed by the new extensions. To clear the list, specify .SUFFIXES: Note: Only those extensions specified in .SUFFIXES can have inference rules. NMAKE ignores inference rules unless the extensions have been specified in a .SUFFIXES list. ΓòÉΓòÉΓòÉ <hidden> NMAKE - .PRECIOUS Pseudotarget ΓòÉΓòÉΓòÉ Syntax: .PRECIOUS : targets... This pseudotarget tells NMAKE not to delete a target even if the commands that build it are terminated or interrupted. This pseudotarget overrides the NMAKE default. By default, NMAKE deletes the target if it cannot be sure that the target was built successfully. For example, .PRECIOUS : TOOLS.LIB TOOLS.LIB : A2Z.OBJ Z2A.OBJ command : If the commands to build TOOLS.LIB are interrupted, leaving an incomplete file, NMAKE does not delete the partially built TOOLS.LIB. Note: The pseudotarget .PRECIOUS is useful only in limited circumstances. Most professional development tools have their own interrupt handlers and "clean up" when errors occur. ΓòÉΓòÉΓòÉ <hidden> NMAKE - In-Line Files ΓòÉΓòÉΓòÉ Example You may need to issue a command in the description file with a list of arguments exceeding the command-line limit of the operating system. Just as NMAKE supports the use of command files, it can also generate in-line files which are read as response files by other programs. To generate an in-line file, use the following syntax for your description block: target : dependents command @<<[filename] in-line file text << [KEEP | NOKEEP] All of the text between the two sets of double brackets (<<) is placed into an in-line file and given the name <filename>. You can refer to the in-line file at a later time by using <filename>. If <filename> is not given, NMAKE gives the file a unique name in the directory specified by the TMP environment variable if it is defined. Otherwise, NMAKE creates a unique filename in the current directory. The in-line file can be temporary or permanent. If you do not specify otherwise, or if you specify the keyword NOKEEP, the in-line file is temporary. Specify KEEP to retain the file. Note: The at sign (@) is not part of the NMAKE syntax but is the typical character used by utilities (such as LINK386) to designate a file as a response file. ΓòÉΓòÉΓòÉ <hidden> NMAKE - In-Line Files Example ΓòÉΓòÉΓòÉ In-Line Files MATH.LIB : ADD.OBJ SUB.OBJ MUL.OBJ DIV.OBJ LIB @<< MATH.LIB -+ADD.OBJ-+SUB.OBJ-+MUL.OBJ-+DIV.OBJ listing << The above example creates an in-line file and uses it to invoke the Library Manager (LIB). The in-line file is used as a response file by (LIB). It specifies which library to use, the commands to execute, and the listing file to produce. The in-line file contains the following: MATH.LIB -+ADD.OBJ-+SUB.OBJ-+MUL.OBJ-+DIV.OBJ listing Since no file name is listed after the LIB command, the in-line file is given a unique name and placed into the current directory (or the directory defined by the TMP environment variable). ΓòÉΓòÉΓòÉ <hidden> NMAKE - Escape Characters ΓòÉΓòÉΓòÉ NMAKE uses the following punctuation characters in its syntax: ( ) # $ ^ \ { } ! @ - To use one of these characters in a command and not have it interpreted by NMAKE, use a caret ( ^ ) in front of the character. For example, BIG^#.C is treated as BIG#.C With the caret, you can include a literal newline character in a description file. This capability is useful in macro definitions, as in the following example: XYZ=abc^<ENTER> def The effect is equivalent to the effect of assigning the C-style string abc\ndef to the XYZ macro. Note that this effect differs from the effect of using the backslash ( \ ) to continue a line. A newline character that follows a backslash is replaced with a space. NMAKE ignores a caret that is not followed by any of the characters it uses in its syntax. A caret that appears within quotation marks is not treated as an escape character. Note: The escape character cannot be used in the command portion of a dependency block. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Characters that Modify Commands ΓòÉΓòÉΓòÉ Any of three characters can be placed in front of a command to modify how the command is run: - (dash) Turns off error checking for the command @ (at sign) Suppresses display of the command ! (exclamation point) Executes the command for each dependent file Note: o Spaces can separate the modifying character from the command. Any command on a separate line - whether modified or not - must be indented by one or more spaces or tabs. o You can use more than one character to modify a single command. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Turn Error Checking Off (-) ΓòÉΓòÉΓòÉ Example Syntax: -[n] command The /I option globally turns command error-checking off. The dash (-) command modifier overrides the global setting to turn error checking off for commands individually. This modifier is used in two ways: o A dash without a number turns off all error checking. o A dash followed by a number causes NMAKE to abort only if the exit code returned by the command is greater than the number. See Ignore Exit Codes (/I) ΓòÉΓòÉΓòÉ <hidden> NMAKE - Dash Command Modifier Examples ΓòÉΓòÉΓòÉ Error Check Off LIGHT.LST : LIGHT.TXT - FLASH LIGHT.TXT In the example above, NMAKE never aborts, regardless of the exit code returned by FLASH. LIGHT.LST : LIGHT.TXT -1 FLASH LIGHT.TXT In the example above, NMAKE aborts if the exit code returned by FLASH is greater than 1. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Suppress Command Display (@) ΓòÉΓòÉΓòÉ Example Syntax: @ command The /S option globally suppresses the display of commands while NMAKE is running. The at sign (@) modifier suppresses the display for individual commands. Note: Regardless of the /S option or the @ modifier, output generated by the command itself always appears. See Suppress Command Display (/S) ΓòÉΓòÉΓòÉ <hidden> NMAKE - At Sign (@) Command Modifier Example ΓòÉΓòÉΓòÉ Suppress Command Display (@) SORT.EXE:SORT.OBJ @ ECHO sorting The command line calling the ECHO command is not displayed. The output of the ECHO command, however, is displayed. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Execute Command for Dependents (!) ΓòÉΓòÉΓòÉ Syntax: ! command The exclamation-point command modifier causes the command to be executed for each dependent file if the command uses one of the special macros $? or $**. The $? macro refers to all dependent files out-of-date with respect to the target. The $** macro refers to all dependent files in the description block. See Special Macros ΓòÉΓòÉΓòÉ <hidden> NMAKE - Exclamation Point (!) Command Modifier Examples ΓòÉΓòÉΓòÉ Execute Dependents Command (!) LEAP.TXT : HOP.ASM SKIP.BAS JUMP.C ! print $** lpt1: The description block above executes the following three commands, regardless of the modification dates of the dependent file: print HOP.ASM lpt1: print SKIP.BAS lpt1: print JUMP.C lpt1: LEAP.TXT : HOP.ASM SKIP.BAS JUMP.C ! print $? lpt1: The description block above executes the print command only for those dependent files with modification dates later than that of the LEAP.TXT file. If HOP.ASM and JUMP.C have modification dates later than LEAP.TXT, the following two commands are executed: print HOP.ASM lpt1: print JUMP.C lpt1: ΓòÉΓòÉΓòÉ <hidden> NMAKE - Using a Target in Several Description Blocks ΓòÉΓòÉΓòÉ Using a file as a target in more than one description block causes NMAKE to abort. You can overcome this limitation by using two colons (::) as the target/dependent separator instead of one colon. The following description block is legal: X :: A command X :: B command The following causes NMAKE to abort: X : A command X : B command It is legal to use single colons if the target/dependent lines are grouped above the same commands. The following is legal: X : A X : B command Related Topics Double Colon (::) Target/Dependent Separator Example ΓòÉΓòÉΓòÉ <hidden> NMAKE - Double Colon (::) Target/Dependent Separator Example ΓòÉΓòÉΓòÉ TARGET.LIB :: A.ASM B.ASM C.ASM ML A.ASM B.ASM C.ASM LIB TARGET -+A.OBJ -+B.OBJ -+C.OBJ; TARGET.LIB :: D.C E.C ICC /C D.C E.C LIB TARGET -+D.OBJ -+E.OBJ; These two description blocks both update the library named TARGET.LIB. If any of the assembly-language files have changed more recently than the library file, NMAKE executes the commands in the first block to assemble the source files and update the library. Similarly, if any of the C-language files have changed, NMAKE executes the second group of commands to compile the C files and update the library. ΓòÉΓòÉΓòÉ <hidden> NMAKE - EXTMAKE Syntax ΓòÉΓòÉΓòÉ Description files can use a special syntax to determine the drive, path, base name, and extension of the first dependent file in a description block. This syntax is called the "extmake" syntax. The characters %s represent the complete file specification of the first dependent file. Various parts of the file specification are represented using the syntax %|partsF where <parts> is a combination of the following letters: Letter File-Specification Part p Path d Drive f Base name e Extension The percent symbol (%) is a replacement in DOS and OS/2 command lines. To use the percent symbol in command-line arguments, use a double percent (%%). ΓòÉΓòÉΓòÉ <hidden> NMAKE - Differences between NMAKE and MAKE ΓòÉΓòÉΓòÉ The predecessor of NMAKE was a similar utility called MAKE. NMAKE differs from MAKE in the following ways: o NMAKE can use a command file for command-line arguments. o NMAKE provides more command-line options. o NMAKE no longer evaluates targets sequentially. Instead, it updates the primary targets you specify when you invoke NMAKE, regardless of their positions in the description file. If the dependent files of the primary targets are used as targets in other description blocks, NMAKE ensures that these files are built before it builds the primary targets. o NMAKE provides more special macros. o NMAKE permits substitutions within macros. o NMAKE supports directives placed in the description file. o NMAKE allows you to specify include files in the description file. MAKE assumed that all targets in the description file would be built. Because NMAKE builds the first target in the file unless you specify otherwise, you may need to change your old description files to work with the new utility. Description files written for use with MAKE typically list a series of subordinate targets, followed by a higher-level target that depends on the subordinates. As MAKE executed, it built the targets sequentially, creating the highest-level target at the end. The easiest way to convert these description files is to create a new description block at the top of the file. Give this block a pseudotarget named ALL and set its dependents to all of the other targets in the file. When NMAKE executes the description, it assumes you want to build the target ALL and consequently builds all targets in the file. If your description file already contains a block that builds a single top-level target, you can simply make that block the first in the file. Related Topic NMAKE and MAKE Conversion Example ΓòÉΓòÉΓòÉ <hidden> NMAKE - NMAKE and MAKE Conversion Example ΓòÉΓòÉΓòÉ ONE.OBJ: ONE.C TWO.OBJ: TWO.C THREE.OBJ: THREE.C PROG1.EXE: ONE.OBJ TWO.OBJ THREE.OBJ link ONE TWO THREE, PROG1; X.OBJ: X.C Y.OBJ: Y.C Z.OBJ: Z.C XYZ.EXE: X.OBJ Y.OBJ Z.OBJ link X Y Z, XYZ; Assume the example above is an old MAKE description file named MAKEFILE. Note that it builds two top-level targets, PROG1.EXE and XYZ.EXE. To use this file with the new NMAKE, insert the following as the first line in the file: ALL : PROG1.EXE XYZ.EXE With the addition of this line, ALL becomes the first target in the file. Since NMAKE builds the first target by default, you can invoke NMAKE with NMAKE and it builds both PROG1.EXE and XYZ.EXE. ΓòÉΓòÉΓòÉ <hidden> NMAKE - Macros and Inference Rules in TOOLS.INI ΓòÉΓòÉΓòÉ You can place either macros or inference rules in your TOOLS.INI file. NMAKE looks for the TOOLS.INI file first in the current directory and then in the directory indicated by the INIT environment variable. If NMAKE finds a TOOLS.INI file, it looks for the following tag: [nmake] You can place macros and inference rules below this tag in the same format you would use in a description file. If a macro or inference rule is defined in both the TOOLS.INI file and the description file, the definition in the description file takes precedence. Also, if you use the /R option, the TOOLS.INI file is ignored. Related Topics TOOLS.INI Example Ignore TOOLS.INI File (/R) ΓòÉΓòÉΓòÉ <hidden> NMAKE - TOOLS.INI Example ΓòÉΓòÉΓòÉ [nmake] CC=QCL CFLAGS=-Gc -Gx -W3 -Oat .C.OBJ: $(CC) -c $(CFLAGS) $*.C These lines in the TOOLS.INI file do the following: o Redefine the predefined macro CC by setting it to "QCL" rather than "CL" o Define the CFLAGS macro as "-Gc -Gx -W3 -Oat" o Redefine the predefined inference rule to build .OBJ files from .C source files ΓòÉΓòÉΓòÉ 15. PACK ΓòÉΓòÉΓòÉ Select one: Introduction Starting PACK: Method One Method Two Syntax Definitions Creating a List File Starting UNPACK ΓòÉΓòÉΓòÉ <hidden> PACK - Introduction ΓòÉΓòÉΓòÉ PACK reduces the size of a file by compressing its data. You can use PACK for a single file, or a group of files, thereby reducing the disk space required for your OS/2* application. You can start PACK with a single command from the command line. The input required can be specified in one of two ways: o You can type the names of all the files you want to compress directly in the command line ( Method 1). o You can type the name of a single file that contains a list of all the files you want to compress ( Method 2). When using PACK, select the method that is suitable for you. Include the drive and path if the files are not in the working directory. You can specify file names with any combination of uppercase and lowercase letters. File-name extensions are not required; however, if you specify a file name that has an extension, also type the extension. ΓòÉΓòÉΓòÉ <hidden> Starting PACK: Method 1 ΓòÉΓòÉΓòÉ You can start PACK with a single command from the command line. You can type the names of all the files you want to compress directly in the command line. Include the drive and path if the files are not in the working directory. You can specify file names with any combination of uppercase and lowercase letters. File-name extensions are not required; however, if you specify a file name that has an extension, also type the extension. Example of the command-syntax follows: PACK sourcefile [packedfile] [/H:headerpath\ |/H:headerfile |/H:headerpath\ headerfile] [/D:headerdate] [/T:headertime] [/C] [/A] [/R] where: sourcefile Specifies the name of the file you want packed (compressed). This parameter is required. Include the drive and path if the file is not in the working directory. Global file-name characters are permitted. When the data is compressed, the name of the source file is placed in the header of the compressed file and is used as the destination file name during unpacking. packedfile Specifies the name of the file that will contain the compressed data. Files that contain compressed data can be recognized by the @ symbol as the last character in the file name. If you do not specify this parameter, PACK places the compressed data in sourcefile and modifies its name to contain the @ symbol. /H:headerpath\ or /H:headerfile or /H:headerpath\ headerfile These parameters can be used separately or paired. /H:headerpath\ Specifies the destination path (drive letters are not permitted) to be placed in the header of the file that contains the compressed data. Unless this path is overridden with the UNPACK command, it will be the destination path when the file is uncompressed. Headerpath must end with a back slash (\). /H:headerfile Specifies the name of the file to be placed in the header of the compressed file. This file name will be used as the destination file for the uncompressed data and cannot be overridden. If a header file name is not specified, PACK automatically uses sourcefile as the name of the file that is placed in the header of the compressed file. /H:headerpath\ headerfile Specifies that both a destination path and a destination file name are to be placed in the header of the file that has the compressed data. /D:headerdate Records the date in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The date must follow the format /D:MM-DD-YYYY. For example: /D:08-20-1991 and /D:12-30-2010. /T:headertime Records the time in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The time must follow the format /T:HH.MM. For example /T:02.06 and /T:14.54. Hour 00 represents 12 a.m. and hour 12 represents 12 p.m. /A Adds data from sourcefile to the data in packedfile. The source file can be either in a compressed or uncompressed state. If the source file is in an uncompressed state, the data is compressed before being added to the file containing the compressed data. /C Specifies that the current path be placed in the header of the file that contains the compressed data. When the UNPACK command is used, this path will be the destination path for the file that contains the uncompressed data. You cannot use /C when the headerpath is used. /R Removes the file specified by sourcefile from the file that contains only compressed data. The sourcefile parameter must specify the path and file name exactly as they appear in the header of the file with the compressed data; otherwise, the following error message The specified file to remove was not found. appears on the screen. The /R parameter is valid only when used in conjunction with sourcefile and packedfile. Note: The path and file-name information stored in the header of the file that contains the compressed data can be displayed by using the /SHOW option available with UNPACK. For information about the /SHOW option, see the UNPACK command in the online OS/2 Command Reference. ΓòÉΓòÉΓòÉ <hidden> Starting PACK: Method 2 ΓòÉΓòÉΓòÉ You can start PACK with a single command from the command line. You can type the name of a single file that contains a list of all the files you want to compress. Include the drive and path if the files are not in the working directory. You can specify file names with any combination of uppercase and lowercase letters. File-name extensions are not required; however, if you specify a file name that has an extension, also type the extension. Example of the command-line syntax follows: PACK listfile [packedfile] /L [/H:headerpath\ |/H:headerfile |/H:headerpath\ headerfile] [/D:headerdate] [/T:headertime] [/C] where: listfile Specifies the name of the file that contains a list of files that are to be compressed. When naming a list file, do not use global file-name characters. For information about list files, see Creating a List File packedfile Specifies the name of the file that will contain the compressed data. Files that contain compressed data can be recognized by the @ symbol as the last character in the file name. If you do not specify this parameter, PACK places the compressed data in sourcefile and modifies its name to contain the @ symbol. /H:headerpath\ or /H:headerfile or /H:headerpath\ headerfile These parameters can be used separately or paired. /H:headerpath\ Specifies the destination path (drive letters are not permitted) to be placed in the header of the file that contains the compressed data. Unless this path is overridden with the UNPACK command, it will be the destination path when the file is uncompressed. Headerpath must end with a back slash (\). /H:headerfile Specifies the name of the file to be placed in the header of the compressed file. This file name will be used as the destination file for the uncompressed data and cannot be overridden. If a header file name is not specified, PACK automatically uses sourcefile as the name of the file that is placed in the header of the compressed file. /H:headerpath\ headerfile Specifies that both a destination path and a destination file name are to be placed in the header of the file that has the compressed data. /D:headerdate Records the date in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The date must follow the format /D:MM-DD-YYYY. For example: /D:08-20-1991 and /D:12-30-2010. /T:headertime Records the time in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The time must follow the format /T:HH.MM. For example /T:02.06 and /T:14.54. Hour 00 represents 12 a.m. and hour 12 represents 12 p.m. /C Specifies that the current path be placed in the header of the file that contains the compressed data. When the UNPACK command is used, this path will be the destination path for the file that contains the uncompressed data. You cannot use /C when the headerpath is used. /L Indicates that filename is a list file. A list file is not compressed; it simply contains a listing of the names of the files that are to be compressed. Note: The path and file-name information stored in the header of the file that contains the compressed data can be displayed by using the /SHOW option available with UNPACK. For information about the /SHOW option, see the UNPACK command in the online OS/2 Command Reference. ΓòÉΓòÉΓòÉ <hidden> PACK - Syntax Definitions ΓòÉΓòÉΓòÉ The PACK command line includes the following parameters: sourcefile Specifies the name of the file you want packed (compressed). This parameter is required. Include the drive and path if the file is not in the working directory. Global file-name characters are permitted. When the data is compressed, the name of the source file is placed in the header of the compressed file and is used as the destination file name during unpacking. listfile Specifies the name of the file that contains a list of files that are to be compressed. When naming a list file, do not use global file-name characters. (See Creating a List File.) packedfile Specifies the name of the file that will contain the compressed data. Files that contain compressed data can be recognized by the @ symbol as the last character in the file name. If you do not specify this parameter, PACK places the compressed data in sourcefile and modifies its name to contain the @ symbol. /H:headerpath\ or /H:headerfile or /H:headerpath\ headerfile These parameters can be used separately or paired. /H:headerpath\ Specifies the destination path (drive letters are not permitted) to be placed in the header of the file that contains the compressed data. Unless this path is overridden with the UNPACK command, it will be the destination path when the file is uncompressed. Headerpath must end with a back slash (\). /H:headerfile Specifies the name of the file to be placed in the header of the compressed file. This file name will be used as the destination file for the uncompressed data and cannot be overridden. If a header file name is not specified, PACK automatically uses sourcefile as the name of the file that is placed in the header of the compressed file. /H:headerpath\ headerfile Specifies that both a destination path and a destination file name are to be placed in the header of the file that has the compressed data. /D:headerdate Records the date in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The date must follow the format /D:MM-DD-YYYY. For example: /D:08-20-1991 and /D:12-30-2010. /T:headertime Records the time in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The time must follow the format /T:HH.MM. For example /T:02.06 and /T:14.54. Hour 00 represents 12 a.m. and hour 12 represents 12 p.m. /A Adds data from sourcefile to the data in packedfile. The source file can be either in a compressed or uncompressed state. If the source file is in an uncompressed state, the data is compressed before being added to the file containing the compressed data. /C Specifies that the current path be placed in the header of the file that contains the compressed data. When the UNPACK command is used, this path will be the destination path for the file that contains the uncompressed data. You cannot use /C when the headerpath is used. /L Indicates that filename is a list file. A list file is not compressed; it simply contains a listing of the names of the files that are to be compressed. /R Removes the file specified by sourcefile from the file that contains only compressed data. The sourcefile parameter must specify the path and file name exactly as they appear in the header of the file with the compressed data; otherwise, the following error message The specified file to remove was not found. appears on the screen. The /R parameter is valid only when used in conjunction with sourcefile and packedfile. Note: The path and file-name information stored in the header of the file that contains the compressed data can be displayed by using the /SHOW option available with UNPACK. For information about the /SHOW option, see the UNPACK command in the online OS/2 Command Reference. ΓòÉΓòÉΓòÉ <hidden> PACK - Creating a List File ΓòÉΓòÉΓòÉ To use a list file with PACK, you must first create a file that contains the names of the files you want to compress. You can give the list file any name. Following is an example of specifying a list file at the command line. PACK DEVICE.LST DEVICE.DRV /L The /L indicates that DEVICE.LST is a list file. If the list file is not in the working directory, you must specify the drive and path. Global file-name characters are not permitted in the list-file name. DEVICE.DRV is the destination file for the end-to-end-compressed data. (End-to-end compressed data is the data from each of the files contained in the list file. This data is stored in a contiguous format in the destination file.) You can also get end-to-end compressed data by using global file-name characters. For example: PACK *.EXE BUNDLE The syntax used in the list file is similar to that used in the command line. The syntax for a single line in the list file follows: sourcefile [/H:headerpath\ |/H:headerfile |/H:headerpath\ headerfile] [/D:headerdate] [/T:headertime] [/C] Remember, when using the list-file method (method 2), global file-name characters are not permitted in the source-file name. Notice also that "PACK" is excluded, and packedfile is not permitted in the list file, because they were specified on the command line. You can include comments or blank lines by entering a semicolon as the first character of the line. An example of a list file follows. ;This is a comment C:\OS2\COMMAND.COM CONFIG.SYS /H:CONFIG.BAK /C \OS2\INSTALL\DDINSTAL.EXE /H:\OS2\DDINSTAL.TMP /D:10-15-91 /T:11.45 ΓòÉΓòÉΓòÉ <hidden> PACK - Starting UNPACK ΓòÉΓòÉΓòÉ UNPACK restores a file of compressed data to its original size, and copies it to a specified drive and path. To start the UNPACK command, type: UNPACK sourcefile [destinationdrive:] [destinationpath] [/SHOW] [/N:singlefile] [/V] [/F] where: sourcefile Specifies the name of an existing file that contains compressed data. If this file contains one or more files of compressed data, UNPACK restores each file within the file. destinationdrive: Specifies the name of the drive to which you want UNPACK to copy one or more restored files. When you specify a destination drive but not a path, UNPACK uses the path information stored in the header of the file that contains the compressed data. destinationpath Specifies the name of the directory (and its subdirectories) to which you want UNPACK to copy one or more restored files. When specified, the destination path overrides the path information stored in the header of the file that contains the compressed data. /SHOW Displays the destination path and file-name information that are saved in the header of each file containing compressed data. /N:singlefile Extracts and uncompresses one file from a file that contains multiple files of compressed data. /V Verifies that sectors written to the target disk are recorded properly. This parameter lets you know that critical data has been correctly recorded. This parameter causes UNPACK to run slower because a check is made for each entry recorded on the disk. /F Specifies that files with extended attributes should not be unpacked or copied if the destination file system does not support extended attributes. ΓòÉΓòÉΓòÉ 16. Resource Compiler ΓòÉΓòÉΓòÉ Select One: Introduction Help Using Options Resource Script Files Constants Binary Resource Files About Statements Statements/Directives Error Messages ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Introduction ΓòÉΓòÉΓòÉ The OS/2* Resource Compiler (RC) is an application-development tool that lets you add application resources, such as message strings, pointers, menus, and dialog boxes, to the executable file of your application. The Resource Compiler is primarily intended to prepare data for OS/2 applications that use functions such as WinLoadString, WinLoadPointer, WinLoadMenu, and WinLoadDlg. These functions load resources from the executable file of your application or another specified executable file. The application can then use the loaded resources as needed. The Resource Compiler and the resource functions let you quickly define and/or modify application resources without recompiling the application itself. That is, RC can modify the resources in an executable file at any time without affecting the rest of the file. This means that you can create custom applications from a single executable file - you just use RC to add the custom resources you need to each application. The Resource Compiler is especially important for international applications because it lets you define all language-dependent data, such as message strings, as resources. Preparing the application for a new language is simply a matter of adding new resources to the existing executable file. Note: Make sure the file RCPP.EXE (the Resource Compiler preprocessor) is available for the use of the Resource Compiler. It can be in the current directory, or in a directory to which there is a path. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Command-Line Options ΓòÉΓòÉΓòÉ The following options can be specified on the Resource Compiler command line: -d defname Preprocessor define -Ddefname Preprocessor define -i Include file path -r Create .res file -p Pack - 386 resources will not cross 64K boundaries. -cp cp | lb,tb,... DBCS codepage or lead/trail byte information. -h Access Help -x Causes the resource to be compressed when it is written to the executable. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Help ΓòÉΓòÉΓòÉ To display Resource Compiler help, type RC at the prompt, with no parameters. The appropriate copyright statement will be displayed, along with a list of Resource Compiler options. Usage: rc [<options>] <.RC input file> [<.EXE output file>] -d defname - Preprocessor define -Ddefname - Preprocessor define -i - Include file path -r - Create .res file -p - Pack - 386 resources will not cross 64K boundaries -cp cp | lb,tb,... - DBCS codepage or lead/trail byte information -h - Access Help Environment variables: DBCS=cp | lb,tb,... TMP=temporary file path TEMP=temporary file path INCLUDE=include file path ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Resource Script Files ΓòÉΓòÉΓòÉ This topic describes the resource script file used to define your application resources and explains how to compile the file and add the resources to your executable file. Use the Resource Compiler to perform the following actions: o Create a resource script file. o Compile the file. o Add the file to the executable file of your application (optional). The following sections describe the resource script file and the RC program. Resource Script Files A resource script file consists of one or more resource statements that define the type, identifier, and data for each resource. For example, the following multiple-line resource statement defines a menu to be used with an application: MENU 1 BEGIN MENUITEM "Alpha", 101 MENUITEM "Beta", 102 END A resource script file is a text file you can create by using an ordinary text editor. Since some resources may contain binary data that cannot be created using a text editor, many resource statements let you specify additional files to include when compiling the resource script file. For example, the following statement defines an icon and specifies the file MYICON.ICO as containing the icon data: ICON 1 myicon.ico Directives A resource script file can also contain directives. For example, the following directive includes the header file OS2.H when RC processes the resource script file: #include <os2.h> Resource script files typically have the .RC filename extension. .RC is the default extension; use it for all your resource script files. Note: Although the Resource Compiler is C-like in syntax, it is not a C compiler. Use only the Resource Compiler statements. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Directives ΓòÉΓòÉΓòÉ A directive is a statement that carries out a task such as including a header file, defining constants, or conditionally compiling portions of the resource script file. Directives elif Directive else Directive endif Directive if Directive ifdef Directive ifndef Directive ΓòÉΓòÉΓòÉ <hidden> Using the Resource Compiler ΓòÉΓòÉΓòÉ The Resource Compiler (RC) compiles a resource script file to create a new file called a binary resource file. The binary resource file is added to the executable file of the application, replacing any existing resources in that file. You can start RC in any of three ways. o Compile and add a resource definition file to an executable file o Compile a resource script file o Add a binary resource file to an executable file The RC command line has the following three basic forms: rc resource-script-file [executable-file] rc resource-file [executable-file] rc -r resource-script-file [resource-file] Note: The third option does not add to the executable file. The resource-script-file field must be the filename of the resource script file to be compiled. If the file is not in the current directory, you must provide a full path. If you provide a filename without specifying a filename extension, RC automatically appends the .RC extension to the name. The executable-file field must be the name of the executable file to receive the compiled resources. This is a file having a filename extension of either .EXE or .DLL. If the file is not in the current directory, you must provide a full path. If you omit the executable-file field, RC adds the compiled resources to the executable file that has the same name as the resource script file but which has the .EXE filename extension. If you specify the executable-file field but omit the filename extension, RC will append the .EXE extension. If this executable file does not exist, RC displays an error message. The -r option directs RC to compile the resource script file without adding it to an executable file. You can use this option to prepare a binary resource file that you can add to an executable file at a later time. If you do not explicitly name a binary resource file along with the -r option, RC uses the same name as the resource script file but with the .RES filename extension. The resource-file field must be the name of the binary resource file to be added to the executable file. If the binary resource file does not already exist, rc creates it; otherwise, rc replaces the existing file. If the file is not in the current directory, you must provide a full path. The binary resource file must have the .RES filename extension. For example, to compile the resource script file EXAMPLE.RC, and add the result to the executable file EXAMPLE.EXE, use the following command: rc example You do not need to specify the .RC extension. RC creates the binary resource file EXAMPLE.RES and adds the compiled resource to the executable file EXAMPLE.EXE. To compile the resource script file EXAMPLE.RC into a binary resource file without adding the resources to an executable file, use the following command: rc -r example The compiler creates the binary resource file EXAMPLE.RES. To create a binary resource file that has a name different from the resource script file, use the following command: rc -r example newfile.res To add the compiled resources in the binary resource file EXAMPLE.RES to an executable file, use the following command: rc example.res To specify the name of the executable file, if the name is different from the resource file, use the following command: rc example.res newfile.exe To add the compiled resources to a dynamic-link-library (.DLL) file, use the following command: rc example.res dynalink.dll In addition to -r, RC offers two other command-line options: -k and -d. The -k option lets you specify a code-page identifier or country code. The syntax is as follows: [-k codepage-id | country-code] The codepage-id or country-code field contains one of the Constants. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Constants ΓòÉΓòÉΓòÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöéCODE-PAGE ID ΓöéCOUNTRY CODE ΓöéMEANING Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé932 Γöé81 ΓöéJapan Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé934 Γöé82 ΓöéKorea Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé936 Γöé86 ΓöéChina Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé938 Γöé88 ΓöéTaiwan Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ The -d option lets you define up to eight symbolic constants on the command line. The syntax is as follows: [-d string] [-d string] [...] In the previous example, string is a name, an integer constant, or an expression. The -d option is useful for passing conditional-compilation flags to the RC preprocessor. The following example specifies a Japanese code-page identifier and also defines two symbolic constants to be passed to the preprocessor as conditional-compilation flags. rc -k 932 -d DEBUG -d VERSION=2 example Note: To process directives in the resource script file, RC uses the files RCPP.EXE and RCPP.ERR. Be sure that these files are in the current directory or in a directory specified by your PATH environment variable. RC creates many temporary files and writes them to the directory indicated by the TMP or TEMP environment variable. If RC cannot write these temporary files to this directory, it writes them to the current directory. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - About Resource Statements ΓòÉΓòÉΓòÉ Each resource statement consists of one or more keywords, numbers, character strings, constants, or filenames. You combine these to define the resource type, identifier, and data. Keywords are words that have a special meaning to the Resource Compiler. In a statement, keywords specify the resource type, the load and memory options, and the beginning and end of nested statements. You can use the RC keywords only as specified in the statement syntax. Keywords, except for those specifying directives, can be any combination of uppercase and lowercase letters. Note that the curly braces, { and }, are reserved characters. You can use them in place of the BEGIN and END keywords. Numbers are integers that represent coordinates, dimensions, styles, and other numeric data. You can specify numbers in decimal, octal, or hexadecimal notation: Decimal numbers must contain decimal digits but can start with a minus sign (-) when they represent a negative number. Hexadecimal numbers must contain hexadecimal digits (uppercase or lowercase) and must start with the characters 0x. Octal numbers are similar to hexadecimal numbers, except that a lowercase letter o replaces the x. The following example shows several numbers represented in decimal, octal, and hexadecimal notation: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöéDECIMAL ΓöéOCTAL ΓöéHEXADECIMAL Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé1 Γöé0o1 Γöé0x1 Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé10 Γöé0o12 Γöé0xA Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé255 Γöé0o377 Γöé0xFF Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé-1 Γöé0o177777 Γöé0xFFFF Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé65 535 Γöé0o177777 Γöé0xFFFF Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Statements that create controls in dialog windows and menu items in menus require that you specify an identifier for each control or menu item. Statements that create controls also require you to specify coordinates and dimensions. You specify identifiers, coordinates, and dimensions using integers in the range 0 through 65 535. Optionally, you can use simple expressions that evaluate to integers from 0 through 65 535; this lets you specify identifiers, dimensions, and coordinates that are relative to those of the corresponding dialog window or menu. Character strings represent names, labels, titles, and messages. A character string consists of one or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark (") is required in a string, you must include the double quotation mark twice. The meaning of each character value (that is, the character each value represents) depends on the code page (character set) defined for the resource script file. The Resource Compiler interprets the backslash (\) as an escape character in character strings. You can include any ASCII character in a character string by specifying either \xdd, where dd is the hexadecimal representation of an ASCII character, or \nnn, where nnn is the octal representation of an ASCII character. If a backslash is required in a string, you must include the backslash twice. Constants are names that have been assigned values by using the define directive. A constant can represent a number, a character string, or other data. Most resource statements in a resource script file use constants, and many use the constants defined in the OS/2* header files (for example, os2.h). For this reason, you should always use the include directive to include OS2.H in your resource script file. Filenames are OS/2 filenames. If the specified file is not in the current directory, you must specify the drive, directory, and filename. Resource statements have three basic forms: Single-line statements Multiple-line statements Directives Single-line statements consist of a keyword identifying the resource type, a constant or number specifying the resource identifier, and a filename specifying the file containing the resource data. For example, this ICON statement defines an icon resource: ICON 1 myicon.ico The icon resource has the icon identifier 1. The file MYICON.ICO contains the icon data. Multiple-line statements consist of a keyword identifying the resource type, a constant or number specifying the resource identifier, and, between the BEGIN and END keywords, additional resource statements that define the resource data. For example, this MENU statement defines a menu resource: MENU 1 BEGIN MENUITEM "Alpha", 101 MENUITEM "Beta", 102 END The menu identifier is 1. The menu contains two MENUITEM statements that define the contents of the menu. In multiple-line statements such as DLGTEMPLATE and WINDOWTEMPLATE, RC allows any level of nested statements. For example, the DLGTEMPLATE and WINDOWTEMPLATE statements typically contain a single DIALOG or FRAME statement. These statements can contain any number of WINDOW and CONTROL statements; the WINDOW and CONTROL statements can contain additional WINDOW and CONTROL statements; and so on. The nested statements let you define controls and other child windows for the dialog boxes and windows. If a nested statement creates a child window or control, the parent and owner of the new window is the window created by the containing statement. (FRAME statements occasionally create frame controls whose parent and owner windows are not the same.) Directives consist of the reserved character # in the first column of a line, followed by the directive keyword and any additional numbers, character strings, or filenames. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Binary Resource Files ΓòÉΓòÉΓòÉ The binary resource file created by the Resource Compiler consists of one or more resource entries, each in the following form: struct { UCHAR fResType; USHORT usResType; UCHAR fResID; USHORT resid; USHORT fsOptions; ULONG cb; BYTE bytes[1]; }; The fields in each entry have the following meanings: Restype Specifies whether the resource-type identifier is a string or an integer. For OS/2* , the resource type is always an integer and this field is set to 0xFF. _ResType Specifies the resource-type identifier. This value is an integer in the range 0 through 65 535. The following resource types are predefined: RT_ACCELTABLE Accelerator table RT_BITMAP Bit map RT_CHARTBL Character table RT_DIALOG Dialog template RT_DISPLAYINFO Display information RT_DLGINCLUDE Dialog include-file name RT_FKALONG Long-form function-key area RT_FKASHORT Short-form function-key area RT_FONT Font RT_FONTDIR Font directory RT_HELPSUBTABLE Help subtable RT_HELPTABLE Help table RT_KEYTBL Key table RT_MENU Menu template RT_MESSAGE Error-message table RT_POINTER Mouse-pointer shape RT_RCDATA Binary data RT_STRING String table RT_VKEYTBL Virtual key table ResID Specifies whether the resource identifier is a string or an integer. For OS/2, the resource identifier is always an integer and this field is set to 0xFF. resid Specifies the resource identifier. This value is an integer in the range 0 through 65 535. Options Specifies the load and memory options. This value can be a combination of the following: 0x0010 MOVEABLE resource. If not given, the resource is FIXED. 0x0040 PRELOAD resource. If not given, the resource is LOADONCALL. 0x1000 DISCARDABLE resource. cb Specifies the size of the resource (in bytes). bytes Contains the resource. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Statements ΓòÉΓòÉΓòÉ The following statements and directives are used by the Resource Compiler (RC): ACCELTABLE Statement ASSOCTABLE Statement AUTOCHECKBOX Statement AUTORADIOBUTTON Statement BITMAP Statement CHECKBOX Statement CODEPAGE Statement COMBOBOX Statement CONTAINER Statement CONTROL Statement CTEXT Statement CTLDATA Statement define Directive DEFPUSHBUTTON Statement DIALOG Statement DLGINCLUDE Statement DLGTEMPLATE Statement EDITTEXT Statement elif Directive else Directive endif Directive ENTRYFIELD Statement FONT Statement FRAME Statement GROUPBOX Statement HELPITEM Statement HELPSUBITEM Statement HELPSUBTABLE Statement HELPTABLE Statement ICON Statement (Resource) ICON Statement (Control) if Directive ifdef Directive ifndef Directive include Directive LISTBOX Statement LTEXT Statement MENU Statement MENUITEM Statement MESSAGETABLE Statement MLE Statement NOTEBOOK Statement POINTER Statement PRESPARAMS Statement PUSHBUTTON Statement RADIOBUTTON Statement RCDATA Statement RCINCLUDE Statement RESOURCE Statement RTEXT Statement SLIDER Statement SPINBUTTON Statement STRINGTABLE Statement SUBITEMSIZE Statement SUBMENU Statement undef Directive VALUESET Statement WINDOW Statement WINDOWTEMPLATE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ACCELTABLE Statement ΓòÉΓòÉΓòÉ Syntax: ACCELTABLE acceltable-id [mem-option] BEGIN key-value, command[, accelerator-options] . . . END Description The ACCELTABLE statement creates a table of accelerators for an application. An accelerator is a keystroke that gives the user a quick way to choose a command from a menu or carry out some other task. An accelerator table can be loaded when needed from the executable file by using the WinLoadAccelTable function. You can provide any number of ACCELTABLE statements in a resource script file. Each statement must specify a unique table identifier. You can provide any number of accelerator definitions in an accelerator table; however, no two definitions in a table can specify the same key. Each accelerator definition must specify a key value and command. The WinSetAccelTable function used in the application translates the accelerator keystroke into a WM_COMMAND, WM_HELP, or WM_SYSCOMMAND message that has the corresponding command value. The message type depends on the accelerator-option field. acceltable-id Specifies the accelerator-table identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. Each accelerator table in a resource script file must have a unique identifier. mem-option Specifies how the system manages the resource when it is in memory. This value must be one of the following: Option Meaning FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. This is the default option. DISCARDABLE System discards the resource if it is no longer needed. key-value Specifies the character, scan, or virtual-key code of the accelerator key. The meaning depends on the accelerator-options field. The key-value field must be a single character enclosed in double-quotation marks or an integer in the range 0 through 255. If you specify an integer, you must specify the CHAR, SCANCODE, or VIRTUALKEY accelerator option; otherwise, the default option is CHAR. Integers must be in decimal or hexadecimal notation. command Specifies the command value for the corresponding WM_COMMAND, WM_HELP, or WM_SYSCOMMAND message. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to an integer in that range. accelerator-options Specifies the accelerator type. This value can be a combination of the following: VIRTUALKEY Specifies that the key-value field is a virtual-key code. SCANCODE Specifies that the key-value field is a keyboard scan code. CHAR Specifies that the key-value field is a character code. SHIFT Specifies that the user must press the Shift key and the key corresponding to the key-value field to generate the accelerator. CONTROL Specifies that the user must press the Ctrl key and the key corresponding to the key-value field to generate the accelerator. ALT Specifies that the user must press the Alt key and the key corresponding to the key-value field to generate the accelerator. LONEKEY Specifies that the user needs to press only the key corresponding to the key-value field to generate the accelerator. SYSCOMMAND Specifies that the accelerator translates to a WM_SYSCOMMAND message. If you do not include this option, the accelerator translates to a WM_COMMAND message. HELP Specifies that the accelerator translates to a WM_HELP message. If you do not include this option, the accelerator translates to a WM_COMMAND message. Note: VIRTUALKEY, SCANCODE, and CHAR are mutually exclusive. SYSCOMMAND and HELP are also mutually exclusive. Comments If two accelerators use the same key with different Shift, Control, or ALT options, you should specify the more restrictive accelerator first in the table. For example, you should place Shift+Enter before Enter. If you include the OS2.H header file, you can use the following constants to specify the accelerator options: Γöé Γöé AF_ALT ΓöéAF_CHAR ΓöéAF_CONTROL ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ AF_HELP ΓöéAF_LONEKEY ΓöéAF_SCANCODE ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ AF_SHIFT ΓöéAF_SYSCOMMAND ΓöéAF_VIRTUALKEY Γöé Γöé To combine these constants, you must use the bitwise OR (|) operator. Example This example creates an accelerator table whose accelerator-table identifier is 1. The table contains two accelerators: Ctrl+S and Ctrl+G. These accelerators generate WM_COMMAND messages with values of 101 and 102, respectively, when the user presses the corresponding keys. ACCELTABLE 1 BEGIN "S", 101, CONTROL "G", 102, CONTROL END ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ASSOCTABLE Statement ΓòÉΓòÉΓòÉ Syntax: ASSOCTABLE assoctable-id [load-option][mem-option] BEGIN association-name, file-match-string[, extended-attribute-flag] [, icon-filename] . . . END Description The ASSOCTABLE statement defines a file-association table for an application. This table associates the data files that an application creates with the executable file of the application. When the user selects one of these data files from File Manager, the associated application begins executing. A file-association table can also associate icons with the data files that an application creates. File Manager uses these icons to identify the data files graphically. Because a file-association table associates icons by file type, all data files having the same file type have the same icon. You can provide any number of ASSOCTABLE statements in a resource script file, but each statement must specify a unique assoctable-id value. The file-association tables are written not only to the resources within your executable file, but also to the .ASSOC extended attribute. However, only the last file-association table specified in the resource script file is actually written to the extended attribute. assoctable-id Specifies the association-table identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the DosGetResource or DosGetResource2 function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. This is the default option. DISCARDABLE System discards the resource if it is no longer needed. association-name Specifies the name of the file type the application recognizes. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the name, you must include the double quotation mark twice. file-match-string Specifies the file-matching string of a particular type of data file that the application creates. This field must contain zero or more characters enclosed in double quotation marks. You can only use characters that are valid in OS/2* filenames and extensions and the OS/2 wildcard characters question mark (?) and asterisk (*). extended-attribute-flag Specifies the extended-attribute options. This value can be a combination of the following: EAF_DEFAULTOWNER Specifies that the application containing the file-association table starts when the user selects any file matching the file-match-string field from File Manager. EAF_REUSEICON Specifies that the icon defined in the previous entry of the file-association table is used as the icon for the current data-file type. EAF_UNCHANGEABLE Specifies that the entry should not be edited. icon-filename Specifies the name of the file containing an icon. File Manager uses this icon to represent all application-created data files matching the file-match-string field. The file must be in the current directory. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - AUTOCHECKBOX Statement ΓòÉΓòÉΓòÉ Syntax: AUTOCHECKBOX text, id, x, y, width, height[, style] Description The AUTOCHECKBOX statement creates an automatic-check-box control. The control is a small rectangle (check box) that contains an X when the user selects it. The specified text is displayed to the right of the check box. An X appears in the square when the user first selects the control and disappears the next time the user selects it. The AUTOCHECKBOX statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_BUTTON. If you do not specify the style, the default style is BS_AUTOCHECKBOX and WS_TABSTOP. text Specifies text that is displayed to the right of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates an automatic-check-box control that is labeled "Italic." AUTOCHECKBOX "Italic", 101, 10, 10, 100, 100 Related Topics AUTORADIOBUTTON CHECKBOX CONTROL DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - AUTORADIOBUTTON Statement ΓòÉΓòÉΓòÉ Syntax: AUTORADIOBUTTON text, id, x, y, width, height[, style] Description The AUTORADIOBUTTON statement creates an automatic-radio-button control. This control is a small circle with the given text displayed to its right. The control highlights the circle and sends a message to its parent window when the user selects the button. The control also removes the selection from any other automatic-radio-button controls in the same group. When the user selects the button again, the control removes the highlight before sending a message. The AUTORADIOBUTTON statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_BUTTON. If you do not specify a style, the default style is BS_AUTORADIOBUTTON. text Specifies text that is displayed to the right of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y This value must be an integer in the range 0 through 65 535 n expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates an automatic-radio-button control that is labeled "Italic." AUTORADIOBUTTON "Italic", 101, 10, 10, 24, 50 Related Topics AUTOCHECKBOX CHECKBOX CONTROL DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - BITMAP Statement ΓòÉΓòÉΓòÉ Syntax: BITMAP bitmap-id [load-option] [mem-option] filename Description The BITMAP statement defines a bit map resource for an application. A bit map resource, typically created using the Icon Editor, is a custom bit map that an application uses in its display or as an item in a menu. The BITMAP statement copies the bit-map resource from the file specified in the filename field and adds it to the application's other resources. A bit-map resource can be loaded from the executable file when needed by using the GpiLoadBitmap function. You can provide any number of BITMAP statements in a resource script file, but each statement must specify a unique bitmap-id value. bitmap-id Specifies the bit-map-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the GpiLoadBitmap function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. This is the default option. DISCARDABLE System discards the resource if it is no longer needed. filename Specifies the name of the file containing the icon resource. If the file is not in the current directory, filename must be preceded by a full path. Example This example defines a bit map whose bit-map identifier is 12. The bit-map resource is copied from the file CUSTOM.BMP. BITMAP 12 custom.bmp Related Topics See "GpiLoadBitmap" in the Presentation Manager Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CHECKBOX Statement ΓòÉΓòÉΓòÉ Syntax: CHECKBOX text, id, x, y, width, height[, style] Description The CHECKBOX statement creates a check-box control. The control is a small rectangle (check box) that has the specified text displayed to the right. The control highlights the rectangle and sends a message to its parent window when the user selects the control. The CHECKBOX statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_BUTTON. If you do not specify a style, the default style is BS_CHECKBOX and WS_TABSTOP. text Specifies text that is displayed to the right of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates a check-box control that is labeled "Italic." CHECKBOX "Italic", 101, 10, 10, 100, 100 Related Topics AUTOCHECKBOX AUTORADIOBUTTON CONTROL DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CODEPAGE Statement ΓòÉΓòÉΓòÉ Syntax: CODEPAGE codepage-id Description The CODEPAGE statement sets the code page for all subsequent resources. The code page specifies the character set used for characters in the resource. If the CODEPAGE statement is not given in a resource script file, RC uses the code page set up for the individual system. If more than one CODEPAGE statement is given in the file, each CODEPAGE statement applies to the resource statements between it and the next CODEPAGE statement. codepage-id Identifies the code page to be used for subsequent resources. This value can be one of the following: 437 United States 850 Multilingual 860 Portuguese 863 Canadian French 932 Japanese Comments You may also specify a code page by placing a code-page identifier in the load-options or memory-options field of any RC statement that uses those fields. Example In this example, the code page for the character-string resources is set to Portuguese (860). CODEPAGE 860 STRINGTABLE BEGIN 1 "Filename not found" 2 "Cannot open file for reading" END ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - COMBOBOX Statement ΓòÉΓòÉΓòÉ Syntax: COMBOBOX text, id, x, y, width, height[, style] Description The COMBOBOX statement creates a combination-box control. This control combines a list-box control with an entry-field control. It allows the user to place the selected item from a list box into an entry field. The COMBOBOX statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_COMBOBOX. If you do not specify a style, the default style is CBS_SIMPLE, WS_GROUP, WS_TABSTOP, and WS_VISIBLE. text Specifies text that is displayed in the entry field of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_COMBOBOX. You can use the bitwise OR (|) operator to combine styles. Example This example creates a combination-box control. COMBOBOX "", 101, 10, 10, 24, 50 Related Topics CONTROL DIALOG Statement ENTRYFIELD Statement LISTBOX Statement MLE Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CONTAINER Statement ΓòÉΓòÉΓòÉ Syntax: CONTAINER id, x, y, width, height, style Description The CONTAINER statement creates a container control within a dialog window. The container control is a visual component that holds objects. The CONTAINER statement defines the identifier, position, dimensions, and attributes of a container control. The predefined class for this control is WC_CONTAINER. If you do not specify a style, the default style is WS_TABSTOP, WS_VISIBLE, and CCS_SINGLESEL. id Specifies the control identifier. This value is any integer 0 through 65535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window containing the container control. y Specifies the y-coordinate of the lower-left corner of the control. This value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window containing the container control. width Specifies the width of the control. This value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The width is in n-character units. height Specifies the height of the control. This value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_CONTAINER. Use the bitwise OR [|] operator to combine styles. Comments A CONTAINER statement is only used in a DIALOG or WINDOW statement. Example This example creates a container control at position (30,30) within the dialog window. The container has a width of 70 character units and a height of 25 character units. Its resource ID is 301. The default style CCS_SINGLESEL has been overridden by the style specification CCS_MULTIPLESEL. The default styles WS_TABSTOP and WS_GROUP are both in effect, though only the latter is specified. #define IDC_CONTAINER 301 #define IDD_CONTAINERDLG 504 DIALOG "Container", IDD_CONTAINERDLG, 23, 6, 120, 280, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR BEGIN CONTAINER IDC_CONTAINER, 30, 30, 70, 200, CCS_MULTIPLESEL | WS_GROUP END Related Topics CONTROL Statement DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CONTROL Statement ΓòÉΓòÉΓòÉ Syntax: CONTROL text, id, x, y, width, height, class[, style] [ data-definitions ] [ BEGIN control-definition . . . END ] Description The CONTROL statement defines a control as belonging to the specified class. The statement defines the position and dimensions of the control within the parent window, as well as the control style. The CONTROL statement is most often used in a DIALOG or WINDOW statement. Typically, several CONTROL statements are used in each DIALOG statement, and each CONTROL statement must have a unique id value. The optional BEGIN and END statements enclose any CONTROL statements that may be given with the control. CONTROL statements given in this manner represent child windows belonging to the control created by the CONTROL statement. text Specifies text that is displayed to the right of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. In the appropriate styles, a tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the parent window. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the parent window. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in 1/8-character units. class Specifies the control class. This value can be one of the classes specified in the table, "Control Classes," ("Control Classes@Control Classes") or the name of the control class enclosed in double quotation marks. style Specifies the control style. This value can be a combination of control styles. You can use the bitwise OR (|) operator to combine styles. data-definitions Specifies a CTLDATA and/or PRESPARAMS statement. These statements define control and presentation data for the control. For more information, see CTLDATA and PRESPARAMS Statement. control-definition Specifies a CONTROL statement or any one of several predefined control statements. These statements define the style, position, and dimensions of controls in the control. Comments The CONTROL statement can actually contain any combination of CONTROL, DIALOG, and WINDOW statements. But typically, a CONTROL statement contains no such statements. Example This example creates a pushbutton control with the WS_TABSTOP and WS_VISIBLE styles. CONTROL "OK", 101, 10, 10, 20, 50, WC_BUTTON, BS_PUSHBUTTON | WS_TABSTOP | WS_VISIBLE Related Topics AUTOCHECKBOX AUTORADIOBUTTON CHECKBOX CTLDATA DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement PRESPARAMS Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CTEXT Statement ΓòÉΓòÉΓòÉ Syntax: CTEXT text, id, x, y, width, height[, style] Description The CTEXT statement creates a centered-text control. The control is a simple rectangle displaying the given text centered in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The CTEXT statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of the control. The predefined class for this control is WC_STATIC. If you do not specify a style, the default style is SS_TEXT, DT_CENTER, and WS_GROUP. text Specifies text that is centered in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_STATIC. You can use the bitwise OR (|) operator to combine styles. Example This example creates a centered-text control that is labeled "Filename." CTEXT "Filename", 101, 10, 10, 100, 100 Related Topics CONTROL DIALOG Statement LTEXT Statement RTEXT Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - CTLDATA Statement ΓòÉΓòÉΓòÉ Syntax: CTLDATA word-value[, word-value][...] CTLDATA string CTLDATA MENU BEGIN menuitem-definition . . . END Description The CTLDATA statement defines control data for a custom dialog box, window, or control. The statement has three basic forms to permit specifying a menu or specifying data in words or characters. The data can be in any format, since only your window procedure will use it. The window procedure of the dialog box, window, or control receives this data when the item is created. It is up to the window procedure to process the data. word-value Specifies a 16-bit value. This value must be an integer in the range 0 through 65 535. It must be in decimal notation. string Specifies a string of 8-bit characters. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the string, you must include the double quotation mark twice. menuitem-definition Specifies a MENUITEM or SUBMENU statement. These statements define the individual commands or submenus in the given menu. For details about these statements, see MENUITEM Statement and SUBMENU Statement. Comments CTLDATA is often used to supply data that controls the subsequent operation of the custom window. For example, the CTLDATA statement may contain extended style bits - that is, style bits designed specifically for your customized window. You should reserve the CTLDATA statement for window classes that you create yourself. Example This example creates a menu for the window created with the WINDOW statement. WINDOWTEMPLATE 1 BEGIN WINDOW "Sample", 1, 0, 0, 100, 100, "MYCLASS", 0, FCF_STANDARD CTLDATA MENU BEGIN MENUITEM "Exit", 101 END END Related Topics CONTROL DIALOG Statement FRAME Statement MENUITEM Statement PRESPARAMS Statement SUBMENU Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - define Directive ΓòÉΓòÉΓòÉ Syntax: define name value Description The define directive assigns the given value to the specified name. All subsequent occurrences of the name are replaced by the value. name Specifies the name to be defined. This value is any combination of letters, digits, and punctuation. value Specifies any integer, character string, or line of text. This value can contain another defined name, which creates a level of nested defines. You are limited to 64 levels of nested defines. Example This example assigns values to the names "NONZERO" and "USERCLASS". #define NONZERO 1 #define USERCLASS "MyControlClass" Related Topics Directives ifdef Directive ifndef Directive undef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - DEFPUSHBUTTON Statement ΓòÉΓòÉΓòÉ Syntax: DEFPUSHBUTTON text, id, x, y, width, height[, style] Description The DEFPUSHBUTTON statement creates a default pushbutton control. The control is a round-cornered rectangle containing the given text. The rectangle has a bold outline to represent that it is the default response for the user. The control sends a message to its parent window when the user chooses the control. The DEFPUSHBUTTON statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of the control. The predefined class for this control is WC_BUTTON. If you do not specify a style, the default style is BS_PUSHBUTTON, BS_DEFAULT, and WS_TABSTOP. text Specifies text that is centered in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates a default pushbutton control that is labeled "Cancel." DEFPUSHBUTTON "Cancel", 101, 10, 10, 24, 50 Related Topics AUTOCHECKBOX AUTORADIOBUTTON CHECKBOX CONTROL DIALOG Statement GROUPBOX Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - DIALOG Statement ΓòÉΓòÉΓòÉ Syntax: DIALOG text, id, x, y, width, height[, [style][, framectl]][data-definitions] BEGIN control-definition . . . END Description The DIALOG statement defines a window that an application can use to create dialog boxes. The statement defines the position and dimensions of the dialog box on the screen, as well as the dialog-box style. The DIALOG statement is most often used in a DLGTEMPLATE statement. Typically, you use only one DIALOG statement in each DLGTEMPLATE statement, and the DIALOG statement contains at least one control definition. text Specifies the dialog-box title if the style specifies a title bar. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the title, you must include the double quotation mark twice. id Specifies the dialog-box identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the dialog box. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in dialog units, but its exact meaning depends on the dialog style. See the "Comments" section for details. y Specifies the y-coordinate of the lower-left corner of the dialog box. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in dialog units, but its exact meaning depends on the dialog style. See the "Comments" section for details. width Specifies the width of the dialog box. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in n-character units. height Specifies the height of the dialog box. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in 1/8-character units. style Specifies the dialog-box style. This value can be any of the window, dialog-box, or frame styles. You can use the bitwise OR (|) operator to combine styles. framectl Specifies the styles for frame controls belonging to the dialog box. This value can be any of the frame-control styles specified in the table, "Frame-Control Flags." ("Frame-Control Flags@Frame-Control Flag") You can use the bitwise OR (|) operator to combine styles. data-definitions Specifies a CTLDATA and/or PRESPARAMS statement. These statements define control and presentation data for the dialog box. For more information, see CTLDATA and PRESPARAMS Statement. control-definition Specifies a CONTROL statement or any one of several predefined control statements. These statements define the style, position, and dimensions of controls in the dialog box. Comments The exact meaning of the coordinates depends on the style defined by the style field. For dialog boxes with FS_SCREENALIGN style, the coordinates are relative to the origin of the display screen. For dialog boxes with the style FS_MOUSEALIGN, the coordinates are relative to the position of the mouse pointer at the time the dialog box is created. For all other dialog boxes, the coordinates are relative to the origin of the parent window. The DIALOG statement can actually contain any combination of CONTROL, DIALOG, and WINDOW statements. Typically, a DIALOG statement contains one or more CONTROL statements. Example This example creates a dialog box that is labeled "Disk Error." DLGTEMPLATE 1 BEGIN DIALOG "Disk Error", 100, 10, 10, 300, 110 BEGIN CTEXT "Select One:", 1, 10, 80, 280, 12 RADIOBUTTON "Retry", 2, 75, 50, 60, 12 RADIOBUTTON "Abort", 3, 75, 30, 60, 12 RADIOBUTTON "Ignore", 4, 75, 10, 60, 12 END END Related Topics CONTROL CTLDATA DLGTEMPLATE Statement PRESPARAMS Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - DLGINCLUDE Statement ΓòÉΓòÉΓòÉ Syntax: DLGINCLUDE id filename Description The DLGINCLUDE statement adds the specified filename to the resource file. The DLGINCLUDE statement is typically used to let the application access the definitions file for the dialog box with the corresponding identifier. The file named by filename must contain the define directives used by the dialog box. You can provide any number of DLGINCLUDE statements in a resource script file, but each must have a unique identifier. id Specifies the dialog-box identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. filename Specifies the name of the file containing the define directives. If the file is not in the current directory, filename must be preceded by a full path. Example This example includes the name of the definition file dlgdef.h. The dialog-box identifier is 5. DLGINCLUDE 5 \\INCLUDE\\DLGREF.H Related Topics define Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - DLGTEMPLATE Statement ΓòÉΓòÉΓòÉ Syntax: DLGTEMPLATE dialog-id load-option mem-option BEGIN dialog-definition . . . END Description The DLGTEMPLATE statement creates a dialog-box template. A dialog-box template consists of a series of statements that define the identifier, load and memory options, dialog-box dimensions, and controls in the dialog box. The dialog-box template can be loaded from the executable file by using the WinLoadDlg function. You can provide any number of dialog-box templates in a resource script file, but each template must have a unique dialog-id value. dialog-id Specifies the dialog-box identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinLoadDlg function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. dialog-definition Specifies a DIALOG statement. The statement defines the dimensions and style of the given dialog box. For details about the statement, see DIALOG Statement. Comments A DLGTEMPLATE statement can actually contain DIALOG, CONTROL, and WINDOW statements. Typically, you include only one DIALOG statement. Example This example uses a DLGTEMPLATE statement to create a dialog box. DLGTEMPLATE ID_GETTIMER BEGIN DIALOG "Timer", 1, 10, 10, 100, 40 BEGIN LTEXT "Time (0 - 15):", 4, 8, 24, 72, 12 ENTRYFIELD "0", ID_TIME, 80, 28, 16, 8, ES_MARGIN DEFPUSHBUTTON "Enter", ID_TIMEOK, 10, 6, 36, 12 PUSHBUTTON "Cancel", ID_TIMECANCEL, 52, 6, 40, 12 END END Related Topics CONTROL DIALOG Statement WINDOW Statement See "WinLoadDlg" in the Presentation Manager Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - EDITTEXT Statement ΓòÉΓòÉΓòÉ Syntax: EDITTEXT text, id, x, y, width, height, style Description The EDITTEXT statement creates an entry-field control. This control is a rectangle in which the user can type and edit text. The control displays a pointer when the user selects the control. The user can then use the keyboard to enter text or edit the existing text. Editing keys include the BACKSPACE and DELETE keys. By using the mouse or the DIRECTION keys, the user can select the character or characters to delete or select the place to insert new characters. The EDITTEXT statement defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_ENTRYFIELD. If you do not specify a style, the default style is ES_AUTOSCROLL and WS_TABSTOP. text Specifies text that is displayed in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value is any integer 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value is any integer 0 through 65 535, or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. y Specifies the y-coordinate of the lower-left corner of the control. This value is any integer 0 through 65 535, or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. width Specifies the width of the control. This value is any integer 1 through 65 535, or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value is any integer 1 through 65 535, or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_ENTRYFIELD. You can use the bitwise OR ( | ) operator to combine styles. Comments The EDITTEXT control statement is identical to the ENTRYFIELD control statement. Use the EDITTEXT statement only in a DIALOG or WINDOW statement. Example This example creates an entry-field control that is not labeled. EDITTEXT "", 101, 10, 10, 24, 50 Related Topics CONTROL Statement DIALOG Statement ENTRYFIELD Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - elif Directive ΓòÉΓòÉΓòÉ Syntax: elif constant-expression Description The elif directive marks an optional clause of a conditional-compilation block defined by a ifdef, ifndef, or if directive. The directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, elif directs the compiler to continue processing statements up to the next endif, else, or elif directive and then skip to the statement after endif. If the constant expression is zero, elif directs the compiler to skip to the next endif, else, or elif directive. You can use any number of elif directives in a conditional block. constant-expression Specifies the expression to be checked. This value is a defined name, an integer constant, or an expression consisting of names, integers, and arithmetic and relational operators. Example In this example, elif directs the compiler to process the second BITMAP statement only if the value assigned to the name "Version" is less than 7. The elif directive itself is processed only if Version is greater than or equal to 3. #if Version < 3 BITMAP 1 errbox.bmp #elif Version < 7 BITMAP 1 userbox.bmp #endif Related Topics Directives Directives else Directive endif Directive if Directive ifdef Directive ifndef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - else Directive ΓòÉΓòÉΓòÉ Syntax: else Description The else directive marks an optional clause of a conditional-compilation block defined by a ifdef, ifndef, or if directive. The else directive must be the last directive before the endif directive. This directive has no arguments. Example This example compiles the second BITMAP statement only if the name "DEBUG" is not defined. #ifdef DEBUG BITMAP 1 errbox.bmp #else BITMAP 1 userbox.bmp #endif Related Topics Directives elif Directive endif Directive if Directive ifdef Directive ifndef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - endif Directive ΓòÉΓòÉΓòÉ Syntax: endif Description The endif directive marks the end of a conditional-compilation block defined by a ifdef directive. One endif is required for each if, ifdef, or ifndef directive. This directive has no arguments. Related Topics Directives elif Directive else Directive if Directive ifdef Directive ifndef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ENTRYFIELD Statement ΓòÉΓòÉΓòÉ ENTRYFIELD text, id, x, y, width, height , style The ENTRYFIELD statement creates an entry-field control. This control is a rectangle in which the user can type and edit text. The control displays a pointer when the user selects the control. The user can then use the keyboard to enter text or edit the existing text. Editing keys include the BACKSPACE and DELETE keys. By using the mouse or the DIRECTION keys, the user can select the character or characters to delete or select the place to insert new characters. The ENTRYFIELD statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_ENTRYFIELD. If you do not specify a style, the default style is ES_AUTOSCROLL and WS_TABSTOP. text Specifies text that is displayed in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_ENTRYFIELD. You can use the bitwise OR (|) operator to combine styles. Example This example creates an entry-field control that is not labeled. ENTRYFIELD "", 101, 10, 10, 24, 50 Related Topics CONTROL DIALOG Statement MLE Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - FONT Statement ΓòÉΓòÉΓòÉ Syntax: FONT font-id load-option mem-option filename Description The FONT statement defines a font resource for an application. A font resource, typically created by using the OS/2* Font Editor, is a bit map defining the shape of the individual characters in a character set. The FONT statement copies the font resource from the file specified in the filename field and adds it to the other resources of the application. A font resource can be loaded from the executable file when needed by using the GpiLoadFonts function. You can provide any number of FONT statements in a resource script file, but each statement must specify a unique font-id value. font-id Specifies the font-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the GpiLoadFonts function. This is the default option. mem-option Specifies how the system manages the resource when it is i memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. filename Specifies the name of the file containing the font resource. If the file is not in the current directory, filename must be preceded by a full path. Example This example defines a font whose font identifier is 5. The font resource is copied from the file cmroman.fon. FONT 5 cmroman.fon Related Topics See "GpiLoadFonts" in the Presentation Manager Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - FRAME Statement ΓòÉΓòÉΓòÉ Syntax: FRAME text, id, x, y, width, height, style[, framectl] data-definitions [ BEGIN window-definition . . . END ] Description The FRAME statement defines a frame window. The statement defines the title, identifier, position, and dimensions of the frame window, as well as the window style. The FRAME statement is most often used in a WINDOWTEMPLATE statement, and typically, only one FRAME statement is used. The FRAME statement, in turn, typically contains at least one WINDOW statement that defines the client window belonging to the frame window. The frame window has no default style. You must use the framectl field to define additional frame controls, such as a title bar and system menu, to be created when the frame window is created. If the text field is not empty, the statement automatically adds a title-bar control to the frame window, whether or not you specify the FCF_TITLEBAR style. Frame controls are given default styles and control identifiers depending on their class. For example, a title-bar control receives the identifier FID_TITLEBAR. text Specifies the title of the frame window. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the name, you must include the double quotation mark twice. id Specifies the window identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the window. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified window. y Specifies the y-coordinate of the lower-left corner of the window. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified window. width Specifies the width of the window. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the window. This value must be a integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the frame and window styles. This value can be a combination of frame styles. You can use the bitwise OR (|) operator to combine styles. framectl Specifies the styles of frame controls belonging to the frame window. This value can be a combination of the styles specified in the table, "Frame-Control Styles." ("Frame-Control Styles@Frame-Control Styles") You can use the bitwise OR (|) operator to combine styles. data-definitions Specifies a CTLDATA and/or PRESPARAMS statement. These statements define control and presentation data for the frame window. For more information, see CTLDATA and PRESPARAMS Statement. window-definition Specifies a WINDOW statement or any one of several predefined control statements. These statements define the style, position, and dimensions of windows or controls in the frame window. Comments The FRAME statement can actually contain any combination of CONTROL, DIALOG, and WINDOW statements. Typically, a FRAME statement contains one WINDOW statement. Example This example creates a standard frame window, with a title bar, a system menu, minimize and maximize boxes, and a vertical scroll bar. The FRAME statement contains a WINDOW statement defining the client window belonging to the frame window. WINDOWTEMPLATE 1 BEGIN FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL BEGIN WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass" END END Related Topics CONTROL CTLDATA PRESPARAMS Statement WINDOW Statement WINDOWTEMPLATE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - GROUPBOX Statement ΓòÉΓòÉΓòÉ Syntax: GROUPBOX text, id, x, y, width, height , style Description The GROUPBOX statement creates a group-box control. The control is a rectangle that groups other controls together. The controls are grouped by drawing a border around them and displaying the given text in the upper-left corner. The GROUPBOX statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_STATIC. If you do not specify a style, the default style is SS_GROUPBOX and WS_TABSTOP. text Specifies text that appears in the upper-left corner of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_STATIC. You can use the bitwise OR (|) operator to combine styles. Example This example creates a group-box control that is labeled "Options." GROUPBOX "Options", 101, 10, 10, 100, 100 Related Topics AUTOCHECKBOX AUTORADIOBUTTON CHECKBOX CONTROL DEFPUSHBUTTON Statement DIALOG Statement PUSHBUTTON Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - HELPITEM Statement ΓòÉΓòÉΓòÉ Syntax: HELPITEM application-window-id, help-subtable-id, extended-helppanel-id Description The HELPITEM statement defines the help items in a help table. The statement, permitted only in a HELPTABLE statement, specifies the resource identifier of an application window for which help is provided, and the resource identifiers of the help subtable and extended help panel associated with the application window. You can provide any number of HELPITEM statements in a HELPTABLE statement. You should provide one HELPITEM statement for each application window for which help is provided. application-window-id Specifies the resource identifier of an application window for which help is provided. help-subtable-id Specifies the resource identifier of the help subtable associated with the specified application window. extended-helppanel-id Specifies the resource identifier of the extended help panel associated with the specified application window. Example This example defines a help item that associates a help subtable called IDSUB_FILEMENU and an extended help panel called IDEXT_APPHLP with an application window called IDWIN_FILEMENU. HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP Related Topics HELPSUBITEM Statement HELPSUBTABLE Statement HELPTABLE Statement SUBITEMSIZE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - HELPSUBITEM Statement ΓòÉΓòÉΓòÉ Syntax: HELPSUBITEM child-window-id, helppanel-id , integer... Description The HELPSUBITEM statement defines the help subitems in a help subtable. This statement, which is permitted only in a HELPSUBTABLE statement, specifies the identifier of a child window for which help is provided, the identifier of the help panel associated with the child window, and one or more optional, application-defined integers. You can provide any number of HELPSUBITEM statements in a HELPSUBTABLE statement. You should provide one HELPSUBITEM statement for each child window for which help is provided. child-window-id Specifies the resource identifier of the child window for which help is provided. helppanel-id Specifies the resource identifier of the help panel associated with the specified child window. integer Specifies optional, application-defined integers. If you use this field, you must include the SUBITEMSIZE statement in the help subtable to specify the size, in words, of each help subitem in the help subtable. For details about this statement, see SUBITEMSIZE Statement. Example This example defines a help subitem that associates a child window called IDCLD_FILEMENU with a help panel called IDHP_FILEMENU. HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU Related Topics HELPITEM Statement HELPSUBTABLE Statement HELPTABLE Statement SUBITEMSIZE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - HELPSUBTABLE Statement ΓòÉΓòÉΓòÉ Syntax: HELPSUBTABLE helpsubtable-id SUBITEMSIZE size BEGIN helpsubitem-definition . . . END Description The HELPSUBTABLE statement defines the contents of a help-subtable resource. A help-subtable resource contains a help-subitem entry for each item that can be selected in an application window. Each of these items should be a child window of the application window specified in the help-table resource. The help subtable should contain a help subitem for each control, child window, and menu item in the application window. You can provide any number of HELPSUBTABLE statements in a resource script file, but each statement must specify a unique helpsubtable-id value. You can also provide any number of helpsubitem-definition statements in the help subtable. These specify the child window for which help is provided, the help panel containing the help text for the child window, and one or more application-defined integers. If you include optional integers in the helpsubitem-definition statements, you must also include a SUBITEMSIZE statement to specify the size, in words, of each help subitem. All help subitems in a help subtable must be the same size. The default size is two words per help subitem. helpsubtable-id Specifies the resource identifier of the help subtable. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. helpsubitem-definition Specifies a HELPSUBITEM statement. A HELPSUBITEM statement specifies a child window, the help panel associated with the child window, and one or more optional, application-defined integers. For details about this statement, see HELPSUBITEM Statement. Example This example creates a help-subtable resource whose help-subtable identifier is IDSUB_FILEMENU. Each HELPSUBITEM statement specifies a child window and a help panel. HELPSUBTABLE IDSUB_FILEMENU BEGIN HELPSUBITEM IDCLD_OPEN, IDPNL_OPEN HELPSUBITEM IDCLD_SAVE, IDPNL_SAVE END Related Topics HELPITEM Statement HELPSUBITEM Statement HELPTABLE Statement SUBITEMSIZE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - HELPTABLE Statement ΓòÉΓòÉΓòÉ Syntax: HELPTABLE helptable-id BEGIN helpitem-definition . . . END Description The HELPTABLE statement defines the contents of a help-table resource. A help-table resource contains a help-item entry for each application window, dialog box, and message box for which help is provided. You can provide any number of HELPTABLE statements in a resource script file, but each statement must specify a unique helptable-id value. You can also provide any number of helpitem-definition statements in the help table. These specify the application windows for which help is provided, the help subtables associated with each application window, and the extended help panels associated with each application window. helptable-id Specifies the resource identifier of the help table. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. helpitem-definition Specifies a HELPITEM statement. A HELPITEM statement specifies an application window and the associated help subtable and extended help panel. For details about this statement, see HELPITEM Statement. Example This example creates a help-table resource whose help-table identifier is 1. Each HELPITEM statement specifies an application window, a help subtable, and an extended help panel. HELPTABLE 1 BEGIN HELPITEM IDWIN_FILEMENU, IDSUB_FILEMENU, IDEXT_APPHLP HELPITEM IDWIN_EDITMENU, IDSUB_EDITMENU, IDEXT_APPHLP END Related Topics HELPITEM Statement HELPSUBITEM Statement HELPSUBTABLE Statement SUBITEMSIZE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ICON Statement (Resource) ΓòÉΓòÉΓòÉ Syntax: ICON icon-id load-option mem-option filename Description This form of the ICON statement defines an icon resource for an application. An icon resource, typically created by using Icon Editor, is a bit map defining the shape of the icon to be used for a given application. The ICON statement copies the icon resource from the file specified in the filename field and adds it to the application's other resources. An icon resource can be loaded when creating a window by using the WinCreateStdWindow function with the FS_ICON style. You can provide any number of ICON statements in a resource script file, but each statement must specify a unique icon-id value. icon-id Specifies the icon-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. A icon-id of 1 has a special meaning; for details, see the "Comment" section. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinCreateStdWindow function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. filename Specifies the name of the file containing the icon resource. If the file is not in the current directory, filename must be preceded by a full path. Comments An icon with an icon-id of 1 is the default icon. The RC program writes the icon not only to the resources in your executable file, but also as the .ICON extended attribute. File Manager will display this icon next to the name of the executable file. Example This example defines an icon whose icon identifier is 11. The icon resource is copied from the file custom.ico. ICON 11 custom.ico Related Topics BITMAP ICON Statement (Control) POINTER Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ICON Statement (Control) ΓòÉΓòÉΓòÉ Syntax: ICON icon-id, id, x, y, width, height , style Description This form of the ICON statement creates an icon control. This control is an icon displayed in a dialog box. The ICON statement, which you can use only in a DIALOG or WINDOW statement, defines the icon-resource identifier, icon-control identifier, position, and attributes of a control window. The predefined class for this control is WC_STATIC. If you do not specify a style, the default style is SS_ICON. For the ICON statement, the width and height fields are ignored; the icon automatically sizes itself. icon-id Specifies the resource identifier of an icon that is defined elsewhere in the resource file. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies a reserved value. Can be set to zero. height Specifies a reserved value. Can be set to zero. style Specifies the control styles. This value can be a combination of the styles specified for WC_STATIC. You can use the bitwise OR (|) operator to combine styles. Example This example creates an icon control whose icon identifier is 99. ICON 99, 101, 10, 10, 0, 0 Related Topics CONTROL DIALOG Statement ICON Statement (Resource) WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - if Directive ΓòÉΓòÉΓòÉ Syntax: if constant-expression Description The if directive controls conditional compilation of the resource file by checking the specified constant expression. If the constant expression is nonzero, if directs the compiler to continue processing statements up to the next endif, else, or elif directive and then skip to the statement after the endif directive. If the constant expression is zero, if directs the compiler to skip to the next endif, else, or elif directive. constant-expression Specifies the expression to be checked. This value is a defined name, an integer constant, or an expression consisting of names, integers, and arithmetic and relational operators. Example This example compiles the BITMAP statement only if the value assigned to the name "Version" is less than 3. #if Version < 3 BITMAP 1 errbox.bmp #endif Related Topics Directives elif Directive else Directive endif Directive if Directive ifdef Directive ifndef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ifdef Directive ΓòÉΓòÉΓòÉ Syntax: ifdef name Description The ifdef directive controls conditional compilation of the resource file by checking the specified name. If the name has been defined by using a define directive or by using the -d command-line option of rc, ifdef directs the compiler to continue with the statement immediately after the ifdef directive. If the name has not been defined, ifdef directs the compiler to skip all statements up to the next endif directive. name Specifies the name to be checked by the directive. Example This example compiles the BITMAP statement only if the name "Debug" is defined. #ifdef Debug BITMAP 1 errbox.bmp #endif Related Topics Directives define Directive endif Directive if Directive ifndef Directive undef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - ifndef Directive ΓòÉΓòÉΓòÉ Syntax: ifndef name Description The ifndef directive controls conditional compilation of the resource file by checking the specified name. If the name has not been defined or if its definition has been removed by using the undef directive, ifndef directs the compiler to continue processing statements up to the next endif, else, or elif directive and then skip to the statement after the endif directive. If the name is defined, ifndef directs the compiler to skip to the next endif, else, or elif directive. name Specifies the name to be checked by the directive. Example This example compiles the BITMAP statement only if the name "Optimize" is not defined. #ifndef Optimize BITMAP 1 errbox.bmp #endif Related Topics Directives elif Directive else Directive endif Directive if Directive ifdef Directive undef Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - include Directive ΓòÉΓòÉΓòÉ Syntax: include filename Description The include directive causes RC to process the file specified in the filename field. This file should be a header file that defines the constants used in the resource script file. Only the define directives in the specified file are processed; all other statements are ignored. filename Specifies the OS/2* name of the file to be included. This value must be an ASCII string enclosed either in double quotation marks (if the file is in the current directory) or in less-than and greater-than characters (<>) (if the file is in the directory specified by the INCLUDE environment variable). You must give a full path enclosed in double quotation marks if the file is not in the current directory or in the directory specified by the INCLUDE environment variable. Comments The filename field is handled as a C string. Therefore, you must include two backslashes wherever one is required in the path. (As an alternative, you can use a single forward slash (/) instead of two backslashes.) Example This example processes the header files OS2.H and HEADERS\MYDEFS.H\I while compiling the resource script file. #include <os2.h> #include "headers\\\\mydefs.h" Related Topics RCINCLUDE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - LISTBOX Statement ΓòÉΓòÉΓòÉ Syntax: LISTBOX id, x, y, width, height, style Description The LISTBOX statement creates commonly used controls for a dialog box or window. The control is a rectangle containing a list of user-selectable strings, such as filenames. The LISTBOX statement, which you can use only in a DIALOG or WINDOW statement, defines the identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_LISTBOX. If you do not specify a style, the default style is WS_TABSTOP. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_LISTBOX. You can use the bitwise OR (|) operator to combine styles. Example This example creates a list-box control whose identifier is 101. LISTBOX 101, 10, 10, 100, 100 Related Topics CONTROL DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - LTEXT Statement ΓòÉΓòÉΓòÉ Syntax: LTEXT text, id, x, y, width, height , style Description The LTEXT statement creates a left-aligned text control. The control is a simple rectangle displaying the given text left-aligned in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The LTEXT statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of the control. The predefined class for this control is WC_STATIC. If you do not specify a style, the default style is SS_TEXT, DT_LEFT, and WS_GROUP. text Specifies text that is left-aligned in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_STATIC. You can use the bitwise OR (|) operator to combine styles. Example This example creates a left-aligned text control that is labeled "Filename." LTEXT "Filename", 101, 10, 10, 100, 100 Related Topics CTEXT CONTROL DIALOG Statement RTEXT Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - MENU Statement ΓòÉΓòÉΓòÉ Syntax: MENU menu-id load-option mem-option BEGIN menuitem-definition . . . END Description The MENU statement defines the contents of a menu resource. A menu resource is a collection of information that defines the appearance and function of an application menu. A menu is a special input tool that lets a user choose commands from a list of command names. A menu resource can be loaded from the executable file when needed by using the WinLoadMenu function. You can provide any number of MENU statements in a resource script file, but each statement must specify a unique menu-id value. You can provide any number of menuitem-definition statements in the menu. These define the submenus and menu items (commands) in the menu. The order of the statements defines the order of the menu items. menu-id Specifies the menu-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinLoadMenu function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. menuitem-definition Specifies a PRESPARAMS, MENUITEM, or SUBMENU statement. You can use one or more PRESPARAMS statements to control the appearance of a menu, such as the font and the foreground and background colors. If used, PRESPARAMS statements must be the first statements following the BEGIN keyword. For details about the PRESPARAMS statement, see PRESPARAMS Statement. MENUITEM and SUBMENU statements define the individual commands or submenus in the given menu. For details about these statements, see MENUITEM Statement and SUBMENU Statement. Example This example creates a menu resource whose menu identifier is 1. The menu contains a menu item named Alpha and a submenu named Beta. The submenu contains two menu items, Item 1 and Item 2. MENU 1 BEGIN MENUITEM "Alpha", 100 SUBMENU "Beta", 101 BEGIN MENUITEM "Item 1", 200 MENUITEM "Item 2", 201, , MIA_CHECKED END END Related Topics MENUITEM Statement PRESPARAMS Statement SUBMENU Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - MENUITEM Statement ΓòÉΓòÉΓòÉ Syntax: MENUITEM text, menu-id, menu-style, menu-attribute Description MENUITEM SEPARATOR The MENUITEM statement creates a menu item for a menu. The statement, permitted only in a MENU or SUBMENU statement, defines the text, identifier, and attributes of a menu item. The system displays the text when it displays the corresponding menu. If the user chooses the menu item, the system generates a WM_COMMAND message that includes the specified menu-item identifier and sends it to the window owning the menu. You can provide any number of MENUITEM statements, but each must have a unique menu-id value. The alternative form of the MENUITEM statement, MENUITEM SEPARATOR, creates a menu separator. A menu separator is a horizontal dividing bar between two menu items in a submenu. The separator is not active - that is, the user cannot choose it, it has no text associated with it, and it has no identifier. text Specifies the text of the menu item. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the string, you must include the double quotation mark twice. The tilde character ( ~ ) and the \t and \a character combinations have special meanings in the string; for details, see the "Comments" section. If the menu-style field is MIS_BITMAP, item-name must be a bit-map identifier instead of a name. The bit-map identifier must have been previously defined using a BITMAP statement, must be preceded by the \b character, and must be enclosed in double quotation marks. menu-id Specifies the menu-item identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. Each identifier must be unique. menu-style Specifies the menu-item style. This value can be a combination of the following: MIS_BITMAP Specifies that item-name is a bit map identifier. MIS_BREAK Specifies that the menu has multiple columns of items in one pull-down menu or multiple lines of menus in the top-level menu. MIS_BREAKSEPARATOR Specifies that the menu has a vertical line between the columns in a pull-down menu. MIS_BUTTONSEPARATOR Specifies that the user can activate the menu item only by using the mouse. The text is centered in the item, rather than left justified. This option is used for the Help item on the right side of the menu bar. MIS_HELP Specifies that the menu item generates a WM_HELP message. MIS_OWNERDRAW Specifies that the menu item is drawn by the owner window. MIS_SEPARATOR Specifies that the menu item is a menu separator. Although the item-name and menu-id fields are ignored, you must still give values if you specify this style. MIS_STATIC Specifies that the user cannot choose the menu item. MIS_SUBMENU Specifies that the MENUITEM statement is to be treated as a SUBMENU statement. When you specify this option, you must follow the MENUITEM statement with a BEGIN and END clause, as in a SUBMENU statement. You may include a PRESPARAMS statement immediately after the BEGIN keyword. MIS_SYSCOMMAND Specifies that the menu item generates a WM_SYSCOMMAND message. MIS_TEXT Specifies that item-name is a character string. This is the default option. menu-attribute Specifies the menu-item attributes. This value can be a combination of the following: MIA_CHECKED Places a check mark next to the menu-item name. MIA_DISABLED Disables the menu item, preventing the system from generating a message when the user chooses the command. MIA_FRAMED Places a frame (heavy border) around the menu item. MIA_HILITED Places a highlight on the menu-item name when it is displayed, by inverting the name and background. MIA_NODISMISS Causes a submenu or menu item to remain displayed after the user chooses an item. Comments You can use the \t or \a character combination in any item name. The \t character inserts a tab when the name is displayed and is typically used to separate the menu-item name from the name of an accelerator key. The \a character aligns to the right all text that follows it. These characters are intended to be used for menu items in submenus only. The width of the displayed submenu is always adjusted so that there is at least one space (and usually more) between any pieces of text separated by a \t or a \a. (When compiling the menu resource, the compiler stores the \t and \a characters as control characters. For example, the \t is stored as 0x09.) A tilde ( ~ ) character in the item name indicates that the following character is used as a mnemonic character for the item. When the menu is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the menu item by pressing the key corresponding to the underlined mnemonic character. Example This example creates a menu item named Alpha. The item identifier is 101. MENUITEM "Alpha", 101 This example creates a menu item named Beta. The item identifier is 102. The menu item has a text style and a checked attribute. MENUITEM "Beta", 102, MIS_TEXT, MIA_CHECKED This example creates a menu separator between menu items named Gamma and Delta. MENUITEM "Gamma", 103 MENUITEM SEPARATOR MENUITEM "Delta", 104 This example creates a menu item that has a bit map instead of a name. The bit-map identifier, 1, is first defined using a BITMAP statement. The identifier for the menu item is 301. Note that a sign must be placed in front of the bit map identifier in the MENUITEM statement. BITMAP 1 mybitmap.bmp MENUITEM "#1", 301, MIS_BITMAP Related Topics BITMAP PRESPARAMS Statement SUBMENU Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - MESSAGETABLE Statement ΓòÉΓòÉΓòÉ Syntax: MESSAGETABLE load-option mem-option BEGIN string-id string-definition . . . END Description The MESSAGETABLE statement creates one or more string resources for an application. A string resource is a null-terminated character string that has a unique string identifier. A string resource can be loaded from the executable file when needed by using the DosGetResource or DosGetResource2 function with the RT_MESSAGE resource type. You can provide any number of MESSAGETABLE statements in a resource script file. The compiler treats all the strings from the various MESSAGETABLE statements as if they belonged to a single statement. This means that no two strings in a resource script file can have the same string identifier. Although the MESSAGETABLE and STRINGTABLE statements are nearly identical, most applications use the STRINGTABLE statement instead of the MESSAGETABLE statement to create string resources. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the DosGetResource or DosGetResource2 function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. string-id Specifies the character-string identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. The value can be specified in decimal or hexadecimal notation. Each string identifier in a resource script file must be unique. string-definition Specifies a character string. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the string, you must provide the double quotation mark twice. Comments You can continue a string on multiple lines by terminating the line with a backslash (\) or by terminating the line with a double quotation mark (") and then starting the next line with a double quotation mark. Example This example creates two string resources whose string identifiers are 1 and 2. MESSAGETABLE BEGIN 1 "Filename not found" 2 "Cannot open file for reading" END Related Topics STRINGTABLE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - MLE Statement ΓòÉΓòÉΓòÉ Syntax: MLE text, id, x, y, width, height , style Description The MLE statement creates a multiple-line entry-field control. The control is a rectangle in which the user can type and edit multiple lines of text. The control displays a pointer when the user selects it. The user can then use the keyboard to enter text or edit the existing text. Editing keys include the BACKSPACE and DELETE keys. By using the mouse or the DIRECTION keys, the user can select the character or characters to delete or select the place to insert new characters. The MLE statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_MLE. If you do not specify a style, the default style is MLS_BORDER, WS_GROUP, and WS_TABSTOP. text Specifies text that is displayed in the rectangular area of the control. If the MLS_READONLY style is not specified, the user can edit the text. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_MLE. You can use the bitwise OR (|) operator to combine styles. Example This example creates a multiple-line entry-field control that is not labeled. MLE "", 101, 10, 10, 50, 100 Related Topics CONTROL DIALOG Statement ENTRYFIELD Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - NOTEBOOK Statement ΓòÉΓòÉΓòÉ Syntax: NOTEBOOK id, x, y, width, height, style Description The NOTEBOOK statement creates a notebook control within the dialog window. This control is used to organize information on individual pages so that it can be located and displayed easily. The NOTEBOOK statement defines the identifier, position, dimensions, and attributes of a notebook control. The predefined class for this control is WC_NOTEBOOK. If you do not specify a style, the default style is WS_TABSTOP and WS_VISIBLE. id Specifies the control identifier. The value is any integer 0 through 65535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. y Specifies the y-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. width Specifies the width of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The width is in n-character units. height Specifies the height of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_NOTEBOOK. You can use the bitwise OR [ | ] operator to combine styles. Comments The NOTEBOOK statement is used only in a DIALOG or WINDOW statement. Example This example creates a notebook control at position (20, 20) within the dialog window. The notebook has a width of 200 character units and a height of 32 character units. Its resource ID is 201. The tabs style BKS_ROUNDEDTABS specification overrides the notebook default style of square tabs. The default styles WS_TABSTOP and WS_GROUP are both in effect, though only the latter is specified. #define IDC_NOTEBOOK 201 #define IDD_NOTEBOOKDLG 503 DIALOG "Notebook", IDD_NOTEBOOKDLG, 11, 11, 420, 420, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR BEGIN NOTEBOOK IDC_NOTEBOOK, 20, 20, 200, 400, BKS_ROUNDEDTABS | WS_GROUP END Related Topics CONTROL Statement DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - POINTER Statement ΓòÉΓòÉΓòÉ Syntax: POINTER pointer-id load-option mem-option filename Description The POINTER statement defines a pointer resource for an application. A pointer resource, typically created by using the OS/2* Icon Editor, is a bit map defining the shape of the mouse pointer on the screen. The POINTER statement copies the pointer resource from the file specified in the filename field and adds it to the application's other resources. A pointer resource can be loaded from the executable file when needed by using the WinLoadPointer function. You can provide any number of POINTER statements in a resource script file, but each statement must specify a unique pointer-id value. pointer-id Specifies the pointer-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinLoadPointer function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. filename Specifies the name of the file containing the pointer resource. If the file is not in the current directory, filename must be preceded by a full path. Example This example defines a pointer whose pointer identifier is 10. The pointer resource is copied from the file custom.cur. POINTER 10 custom.cur Related Topics See "WinLoadPointer" in the Presentation Manager Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - PRESPARAMS Statement ΓòÉΓòÉΓòÉ Syntax: PRESPARAMS presparam, value, presparam, value, ... Description The PRESPARAMS statement defines presentation fields that customize a dialog box, menu, window, or control. PRESPARAMS data is a series of types and values. The window procedure of the dialog box, menu, window or control receives and processes this data when the item is created. The data for custom controls can be in any format. presparam Specifies a presentation-field type. value Specifies the presentation-field value. Comments PRESPARAMS is often used to supply data to control the appearance of the customized window when it is first created. For example, the PRESPARAMS statement may specify the colors to be used in the window. Example This example creates a menu resource with a menu identifier of 1. The PRESPARAMS statement specifies that the following three menu items be displayed in the 12-point Helvetica font. MENU 1 BEGIN PRESPARAMS PP_FONTNAMESIZE, "12.Helv" MENUITEM "New", 100 MENUITEM "Open", 101 MENUITEM "Save", 102 END Related Topics CONTROL CTLDATA DIALOG Statement FRAME Statement MENU Statement MENUITEM Statement SUBMENU Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - PUSHBUTTON Statement ΓòÉΓòÉΓòÉ Syntax: PUSHBUTTON text, id, x, y, width, height , style Description The PUSHBUTTON statement creates a pushbutton control. The control is a round-cornered rectangle containing the given text. The control sends a message to its parent whenever the user chooses the control. The PUSHBUTTON statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_BUTTON. If you do not specify a style, the default style is BS_PUSHBUTTON and WS_TABSTOP. text Specifies text that is centered in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates a pushbutton control that is labeled "OK." PUSHBUTTON "OK", 101, 10, 10, 100, 100 Related Topics AUTOCHECKBOX AUTORADIOBUTTON CHECKBOX CONTROL DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement RADIOBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - RADIOBUTTON Statement ΓòÉΓòÉΓòÉ Syntax: RADIOBUTTON text, id, x, y, width, height, style Description The RADIOBUTTON statement creates a radio-button control. The control is a small circle that has the given text displayed to its right. The control highlights the circle and sends a message to its parent window when the user selects the button. The control removes the highlight and sends a message when the button is next selected. The RADIOBUTTON statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of a control window. The predefined class for this control is WC_BUTTON. If you do not specify a style, the default style is BS_RADIOBUTTON. text Specifies text that is displayed to the right of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. A tilde ( ~ ) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_BUTTON. You can use the bitwise OR (|) operator to combine styles. Example This example creates a radio-button control that is labeled "Italic." RADIOBUTTON "Italic", 101, 10, 10, 24, 50 Related Topics AUTOCHECKBOX AUTORADIOBUTTON CHECKBOX CONTROL DEFPUSHBUTTON Statement DIALOG Statement GROUPBOX Statement PUSHBUTTON Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - RCDATA Statement ΓòÉΓòÉΓòÉ Syntax: RCDATA resource-id BEGIN data-definition , data-definition ... . . . END Description The RCDATA statement defines a custom-data resource for an application. The custom data can be in whatever format the application requires. You can provide any number of RCDATA statements in a resource script file, but each statement must specify a unique resource-id value. A custom-data resource can be loaded from the executable file when needed by using the DosGetResource or DosGetResource2 functions with the RT_RCDATA resource type. resource-id Specifies the custom-data identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. data-definition Specifies the custom data. The data may be simple expressions or strings. Example This example defines custom data that has a resource identifier of 5. RCDATA 5 BEGIN "E. A. Poe", 1849, -32, 3L, 0x8000000l, 3+4+5 END Related Topics See "DosGetResource" in the Control Program Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - RCINCLUDE Statement ΓòÉΓòÉΓòÉ Syntax: RCINCLUDE filename Description The RCINCLUDE statement causes RC to process the resource script file specified in the filename field along with the current resource script file. The contents of both files are compiled by RC and the results are placed in one binary resource file and/or executable file. filename Specifies the name of the resource script file to be included. If the file is not in the current directory, filename must be preceded by a full path. Comments RCINCLUDE statements are processed before any other processing is done, including preprocessing by RCPP.EXE, which removes comments, replaces values in the define directives, and so on. When specifying a high performance file system (HPFS) file name on an RCINCLUDE statement, enclose the path and file name in double quotes; for example: RCINCLUDE "d:\project\long dialog.dlg" Double quotes enables the Resource Compiler to recognize a name containing embedded blank characters. Example This example includes the file DIALOGS.RC as part of the current resource script file. RCINCLUDE dialogs.rc Related Topics include Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - RESOURCE Statement ΓòÉΓòÉΓòÉ Syntax: RESOURCE type-id resource-id load-option mem-option filename Description The RESOURCE statement defines a custom resource for an application. A custom resource can be any data in any format. The RESOURCE statement copies the custom resource from the specified file and adds it to the application's other resources. A custom resource can be loaded from the executable file when needed by using the DosGetResource or DosGetResource2 function and specifying the resource's type and resource identifier. You can provide any number of RESOURCE statements in a resource script file, but each statement must specify a unique combination of type-id and resource-id values. That is, RESOURCE statements having the same type-id value are permitted as long as the resource-id value for each is unique. type-id Specifies the custom-resource type. This value must be an integer in the range 256 through 65 535, or a simple expression that evaluates to a value in that range. (Values 0 through 255 are reserved.) resource-id Specifies the custom-resource identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the DosGetResource or DosGetResource2 function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. filename Specifies the name of the file containing the custom resource. If the file is not in the current directory, filename must be preceded by a full path. Example This example defines a custom resource whose type identifier is 300 and whose resource identifier is 14. The custom resource is copied from the file CUSTOM.RES. RESOURCE 300 14 custom.res Related Topics See "DosGetResource" in the Control Program Reference. ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - RTEXT Statement ΓòÉΓòÉΓòÉ Syntax: RTEXT text, id, x, y, width, height , style Description The RTEXT statement creates a right-aligned text control. The control is a simple rectangle displaying the given text right-aligned in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The RTEXT statement, which you can use only in a DIALOG or WINDOW statement, defines the text, identifier, dimensions, and attributes of the control. The predefined class for the control is WC_STATIC. If you do not specify a style, the default style is SS_TEXT, DT_RIGHT, and WS_GROUP. text Specifies text that is right-aligned in the rectangular area of the control. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the text, you must include the double quotation mark twice. id Specifies the control identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. y Specifies the y-coordinate of the lower-left corner of the control. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control. width Specifies the width of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The width is in n-character units. height Specifies the height of the control. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The height is in 1/8-character units. style Specifies the control styles. This value can be a combination of the styles specified for WC_STATIC. You can use the bitwise OR (|) operator to combine styles. Example This example creates a right-aligned text control that is labeled "Filename." RTEXT "Filename", 101, 10, 10, 100, 100 Related Topics CTEXT CONTROL DIALOG Statement LTEXT Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - SLIDER Statement ΓòÉΓòÉΓòÉ Syntax: SLIDER id, x, y, width, height, style Description The SLIDER statement creates a slider control within the dialog window. This control lets the user set, display, or modify a value by moving a slider arm along a slider shaft. The SLIDER statement defines the identifier, position, dimensions, and attributes of a slider control. The predefined class for this control is WC_SLIDER. If you do not specify a style, the default style is WS_TABSTOP and WS_VISIBLE. id Specifies the control identifier. The value is any integer 0 through 65535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. y Specifies the y-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. width Specifies the width of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The width is in n-character units. height Specifies the height of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The height is in 1/8-character units. style Specifies the control styles. The value can be any combination of the styles specified for WC_SLIDER. You can use the bitwise OR [ | ] operator to combine styles. Comments The SLIDER statement is only used in a DIALOG or WINDOW statement. Example This example creates a slider control at position (40, 30) within the dialog window. The slider has a width of 120 character units and a height of 2 character units. Its resource ID is 101. The style specification SLS_BUTTONSLEFT adds buttons to the left of the slider shaft. The default styles WS_TABSTOP and WS_VISIBLE are both in effect, though only the latter is specified. #define IDC_SLIDER 101 #define IDD_SLIDERDLG 502 DIALOG "Slider", IDD_SLIDERDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR BEGIN SLIDER IDC_SLIDER, 40, 30, 120, 16, SLS_BUTTONSLEFT | WS_VISIBLE END Related Topics CONTROL Statement DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - SPINBUTTON Statement ΓòÉΓòÉΓòÉ Syntax: SPINBUTTON id, x, y, width, height, style Description The SPINBUTTON statement creates a spinbutton control within the dialog window. This control gives the user quick access to a finite set of data. The SPINBUTTON statement defines the identifier, position, dimensions, and attributes of a spinbutton control. The predefined class for this control is WC_SPINBUTTON. If you do not specify a style, the default style is WS_TABSTOP, WS_VISIBLE, and SPBS_MASTER. id Specifies the control identifier. The value is any integer 0 through 65535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. y Specifies the y-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. width Specifies the width of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The width is in n-character units. height Specifies the height of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The height is in 1/8-character units. style Specifies the control styles. The value is any combination of the styles specified for WC_SPINBUTTON. You can use the bitwise OR [ | ] operator to combine styles. Comments The SPINBUTTON statement is used only in a DIALOG or WINDOW statement. Example This example creates a spinbutton control at position (80, 20) within the dialog window. The spinbutton has a width of 60 character units and a height of 3 character units. Its resource ID is 302. The style specification SPBS_NUMERICONLY creates a control which accepts only the digits 0-9 and virtual keys. The default styles SPBS_MASTER, WS_TABSTOP, and WS_VISIBLE are all in effect, though only WS_TABSTOP is specified. #define IDC_SPINBUTTON 302 #define IDD_SPINDLG 502 DIALOG "Spin button", IDD_SPINDLG, 11, 11, 200, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR BEGIN SPINBUTTON IDC_SPINBUTTON, 80, 20, 60, 24, SPBS_NUMERICONLY | WS_TABSTOP END Related Topics CONTROL Statement DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - STRINGTABLE Statement ΓòÉΓòÉΓòÉ Syntax: STRINGTABLE load-option mem-option BEGIN string-id string-definition . . . END Description The STRINGTABLE statement creates one or more string resources for an application. A string resource is a null-terminated character string that has a unique string identifier. A string resource can be loaded from the executable file when needed by using the WinLoadString function. You can provide any number of STRINGTABLE statements in a resource script file. The compiler treats all the strings from the various STRINGTABLE statements as if they belonged to a single statement. This means that no two strings in a resource script file can have the same string identifier. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinLoadString function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. string-id Specifies the character-string identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. The value can be specified in decimal or hexadecimal notation. Each string identifier in a resource script file must be unique. string-definition Specifies a character string. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the string, you must include the double quotation mark twice. Comments You can continue a string on multiple lines by terminating the line with a backslash (\) or by terminating the line with a double quotation mark (") and then starting the next line with a double quotation mark. Example This example creates two string resources whose string identifiers are 1 and 2. #define IDS_HELLO 1 #define IDS_GOODBYE 2 STRINGTABLE BEGIN IDS_HELLO "Hello" IDS_GOODBYE "Goodbye" END Related Topics MESSAGETABLE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - SUBITEMSIZE Statement ΓòÉΓòÉΓòÉ Syntax: SUBITEMSIZE size Description The SUBITEMSIZE statement specifies the size, in words, of each help subitem in a help subtable. The minimum size is two words, and each help subitem in a help subtable must be the same size. When used, the SUBITEMSIZE statement must appear after the HELPSUBTABLE statement and before the BEGIN keyword. You do not need to use the SUBITEMSIZE statement if the help subitems are the default size (2). size Specifies the size of each help subitem. This value must be an integer. Example The SUBITEMSIZE statement in this example specifies that each HELPSUBITEM statement contains three words. HELPSUBTABLE 1 SUBITEMSIZE 3 BEGIN HELPSUBITEM IDCLD_FILEMENU, IDHP_FILEMENU, 5 HELPSUBITEM IDCLD_HELPMENU, IDHP_HELPMENU, 6 END Related Topics HELPITEM Statement HELPSUBITEM Statement HELPSUBTABLE Statement HELPTABLE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - SUBMENU Statement ΓòÉΓòÉΓòÉ Syntax: SUBMENU text, submenu-id , menu-style BEGIN menuitem-definition . . . END Description The SUBMENU statement creates a submenu for a given menu. A submenu is a vertical list of menu items from which the user can choose a command. You can provide any number of SUBMENU statements in a MENU statement, but each SUBMENU statement must specify a unique submenu-id value. You can provide any number of menuitem-definition statements in the SUBMENU statement. These define the menu items (commands) in the menu. The order of the statements determines the order of the menu items. text Specifies the text of the submenu. This field must contain zero or more characters enclosed in double quotation marks. Character values must be in the range 1 through 255. If a double quotation mark is required in the string, you must include the double quotation mark twice. A tilde ( ~ ) character in the item name indicates that the following character is used as a mnemonic character for the item. When the menu is displayed, the tilde is not shown, but the mnemonic character is underlined. The user can choose the menu item by pressing the key corresponding to the underlined mnemonic character. submenu-id Specifies the submenu identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. menu-style Specifies the submenu style. This value can be a combination of MIS_ values. For details on the MIS_ values, see MENUITEM Statement. menuitem-definition Specifies a PRESPARAMS or MENUITEM statement. You can use the PRESPARAMS statement to control the appearance of a submenu, such as the font and the foreground and background colors. If used, the PRESPARAMS statement must immediately follow the BEGIN keyword. For details about the PRESPARAMS statement, see PRESPARAMS Statement. The MENUITEM statement defines an individual command in the given menu. For details, see MENUITEM Statement. Example This example creates a submenu named Elements. Its identifier is 2. The submenu contains three menu items, which are created by using MENUITEM statements. SUBMENU "Elements", 2 BEGIN MENUITEM "Oxygen", 200 MENUITEM "Carbon", 201, , MIA_CHECKED MENUITEM "Hydrogen", 202 END Related Topics MENU Statement MENUITEM Statement PRESPARAMS Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - undef Directive ΓòÉΓòÉΓòÉ Syntax: undef name Description This directive removes the current definition of the specified name. All subsequent occurrences of the name are processed without replacement. name Specifies the name to be removed. This value is any combination of letters, digits, and punctuation. Example This example removes the definitions for the names "nonzero" and "USERCLASS". #undef nonzero #undef USERCLASS Related Topics Directives define Directive ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - VALUESET Statement ΓòÉΓòÉΓòÉ Syntax: VALUESET id, x, y, width, height, style Description The VALUESET statement creates a value set control within the dialog window. This control lets a user select one choice from a group of mutually exclusive choices. The VALUESET statement defines the identifier, position, dimensions, and attributes of a value set control. The predefined class for this control is WC_VALUESET. If you do not specify a style, the default style is WS_TABSTOP and WS_VISIBLE. id Specifies the control identifier. The value is any integer 0 through 65535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. y Specifies the y-coordinate of the lower-left corner of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The coordinate is assumed to be in dialog units and is relative to the origin of the dialog window. width Specifies the width of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The width is in n-character units. height Specifies the height of the control. The value is any integer 0 through 65535 or an expression consisting of integers and the addition [+] or subtraction [-] operator. The height is in 1/8-character units. style Specifies the control styles. The value is any combination of the styles specified for WC_VALUESET. You can use the bitwise OR [ | ] operator to combine styles. Comments The VALUESET statement is used only in a DIALOG or WINDOW statement. Example This example creates a value set control at position (40, 40) within the dialog window. The value set control has a width of 220 character and a height of 20 character units. Its resource ID is 302. The style specification VS_ICON creates a control to show items in icon form. The default styles WS_TABSTOP and WS_VISIBLE are both in effect, though only WS_TABSTOP is specified. #define IDC_VALUESET 302 #define IDD_VALUESETDLG 501 DIALOG "Value set", IDD_VALUESETDLG, 11, 11, 260, 240, FS_NOBYTEALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR BEGIN VALUESET IDC_VALUESET, 40, 40, 220, 160, VS_ICON | WS_TABSTOP END Related Topics CONTROL Statement DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - WINDOW Statement ΓòÉΓòÉΓòÉ Syntax: WINDOW text, id, x, y, width, height, class , style , framectl data-definitions [ BEGIN control-definition . . . END ] Description The WINDOW statement creates a window of the specified class. The statement defines the position and dimensions of the window relative to its parent window, as well as the window-box style. The WINDOW statement is typically used in a WINDOWTEMPLATE or FRAME statement. Typically, only one WINDOW statement is used in a FRAME statement. It defines the client window belonging to the corresponding frame window. The optional BEGIN and END keywords enclose any CONTROL statements that are given with the window. CONTROL statements given in this manner represent child windows belonging to the window created by the WINDOW statement. text Specifies the window title if the style specifies a title bar. This field must contain zero or more characters enclosed in double quotation marks. The character values must be in the range 1 through 255. If a double quotation mark is required in the title, you must include the double quotation mark twice. id Specifies the window identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. x Specifies the x-coordinate of the lower-left corner of the window. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in dialog units. The position is relative to the origin of the parent window. y Specifies the y-coordinate of the lower-left corner of the window. This value must be an integer in the range 0 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in dialog units. The position is relative to the origin of the parent window. width Specifies the width of the window. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in n-character units. height Specifies the height of the window. This value must be an integer in the range 1 through 65 535 or an expression consisting of integers and the addition (+) or subtraction (-) operator. The value is in 1/8-character units. class Specifies the window class. This value can be one of the control classes specified in the table, "Control Classes" ("Control Classes@Control Classes") or the name of the window class, enclosed in double quotation marks. style Specifies the window style. This value can be any of the window, dialog box, or frame styles specified. framectl Specifies the style of the frame controls belonging to the window. This value can be a combination of the styles specified in the table, "Frame-Control Styles." ("Frame-Control Styles@Frame-Control Styles") You can use the bitwise OR (|) operator to combine styles. data-definitions Specifies a CTLDATA and/or PRESPARAMS statement. These statements define control and presentation data for the window. For more information, see CTLDATA and PRESPARAMS Statement. control-definition Specifies a CONTROL statement or any one of several predefined control statements. These statements define the style, position, and dimensions of controls in the window. Comments The WINDOW statement can actually contain any combination of CONTROL, DIALOG, and WINDOW statements. Typically, a WINDOW statement contains one or no such statements. Example This example creates a client window belonging to the frame window. The client window belongs to the "MyClientClass" window class and has the standard window identifier FID_CLIENT. WINDOWTEMPLATE 1 BEGIN FRAME "My Window", 1, 10, 10, 320, 130, 0, FCF_STANDARD | FCF_VERTSCROLL BEGIN WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass" END END Related Topics CONTROL CTLDATA DIALOG Statement FRAME Statement PRESPARAMS Statement WINDOWTEMPLATE Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - WINDOWTEMPLATE Statement ΓòÉΓòÉΓòÉ Syntax: WINDOWTEMPLATE window-id load-option mem-option BEGIN window-definition . . . END Description The WINDOWTEMPLATE statement creates a window template. A window template consists of a series of statements that define the window identifier, load and memory options, window dimensions, and controls in the window. The window template can be loaded from the executable file by using the WinLoadDlg function. You can provide any number of window templates in a resource script file, but each template must have a unique window-id value. window-id Specifies the window identifier. This value must be an integer in the range 0 through 65 535, or a simple expression that evaluates to a value in that range. load-option Specifies when the system loads the resource from the executable file into memory. This value must be one of the following: PRELOAD System loads the resource when the application starts. LOADONCALL System loads the resource when the application calls the WinLoadDlg function. This is the default option. mem-option Specifies how the system manages the resource when it is in memory. This value must be one or more of the following: FIXED System keeps the resource at a fixed memory location. MOVEABLE System moves the resource as necessary to compact memory. DISCARDABLE System discards the resource if it is no longer needed. The default setting is MOVEABLE and DISCARDABLE. window-definition Specifies a WINDOW statement. The statement defines the dimensions and style of the given window. For details about the statement, see WINDOW Statement. Comments A WINDOWTEMPLATE statement can contain DIALOG, CONTROL, and WINDOW statements. Typically, only one WINDOW statement is used in the WINDOWTEMPLATE statement. Related Topics CONTROL DIALOG Statement WINDOW Statement ΓòÉΓòÉΓòÉ <hidden> Resource Compiler - Error Messages ΓòÉΓòÉΓòÉ The error messages produced by the resource compiler utility (RC) are listed below. In addition to these messages, you may encounter messages produced by the compiler you are using. Error Message Descriptions Accelerator type required (CHAR, SCANCODE, or VIRTUALKEY) Explanation: An acceloption has not been specified in the accelerator table to define the type of accelerator. If the accelerator character code is something other than a single character or a character preceded by a caret ( ^ ), an acceloption is required. Action: Check accelerator table syntax. BEGIN expected in accelerator table Explanation: BEGIN keyword missing from accelerator table. Action: Check syntax. BEGIN expected in dialog or window template Explanation: BEGIN keyword missing from dialog or window template. Action: Check syntax. BEGIN expected in menu Explanation: BEGIN keyword missing from menu. Action: Check syntax. BEGIN expected in message table Explanation: BEGIN keyword missing from message table. Action: Check syntax. BEGIN expected in RCData Explanation: BEGIN keyword missing from RCData table. Action: Check syntax. BEGIN expected in String Table Explanation: BEGIN keyword missing from string table. Action: Check syntax. Cannot re-use message constants Explanation: Message identifier has been used more than once in message table. Action: Check message table syntax. Cannot re-use string constants Explanation: Message identifier has been used more than once in string table. Action: Check string table syntax. Comma expected after item string Explanation: A comma must be used to separate the menu item identifier and the menu item string. Action: Check menu syntax. Control character out of range ( ^A - ^Z) Explanation: Accelerator character codes that use the Ctrl key, and are therefore preceded by a caret ( ^ ), must use alphabetic keys. Action: Check accelerator table syntax. END expected in dialog Explanation: END keyword missing from dialog template. Action: Check syntax. END expected in menu Explanation: END keyword missing from menu. Action: Check syntax. Error creating temp file Explanation: Temporary files are created by the resource compiler during the compilation process. Action: Check that there is sufficient disk space to run the resource compiler, and restart the resource compiler. Expected comma in accelerator table Explanation: Commas are used in the accelerator table to separate the accelerator key, the accelerator command, and the accelerator options. Action: Check accelerator table syntax. Expected ID value for menuitem Explanation: A selection identifier is needed for each item within a menu. Action: Check menu syntax. Expected menu string Explanation: A character string should be specified in the menu definition to describe the menu selection. Action: Check menu syntax. The string should be enclosed in double quotation marks. Expected numeric command value Explanation: A number should be used in the accelerator table to identify the message that is generated by an accelerator key. Action: Check accelerator table syntax. Expected numeric constant in message table Explanation: The identifier that precedes a message definition must be an integer. Action: Check message definition syntax. Expected numeric constant in string table Explanation: The identifier that precedes a string definition must be an integer. Action: Check string definition syntax. Expected numerical dialog constant Explanation: Integers are required in dialog and window templates to specify the coordinates and dimensions of the dialog box. Action: Check syntax of dialog box definition. Expected string in message table Explanation: A character string was not found in the message table. Action: Check syntax. The string should be enclosed in double quotation marks. Expected string in string table Explanation: A character string was not found in the string table. Action: Check string table syntax. The string should be enclosed in double quotation marks. Expected string or constant accelerator command Explanation: The accelerator character code is missing. Action: Check accelerator table syntax. File not found Explanation: The resource compiler could not find the .RC or .RES file that you requested. Action: Check that the file is in the current directory and check the path to the directory. Illegal empty BEGIN/END block found, resource not written Explanation: A BEGIN/END block with no DIALOG, CONTROL, or WINDOW statements in it was found in the dialog template. Action: Delete unwanted BEGIN/END blocks. Invalid accelerator Explanation: The character code specified as an accelerator key must be a valid keyboard operation. Action: Check accelerator key definition syntax. Invalid accelerator option Explanation: The accelerator option must be a valid keyword. Action: Check syntax. Invalid control character Explanation: The accelerator key definition can include an caret ( ^) to specify that the key should be used with the Ctrl key. Action: Check accelerator key definition syntax. Invalid Type Explanation: The resource type must be a valid keyword. Action: Check resource definition syntax. Non-numeric template ID in dialog or window template Explanation: The resource identifier must be an integer. Action: Check dialog or window template syntax. Only one top level window allowed Explanation: Only one DIALOG, CONTROL, or WINDOW statement is allowed within the dialog or window template. Action: Check dialog or window template syntax. Resource Type keyword expected Explanation: The resource type must be specified in the resource script file. Action: Check resource definition syntax. String literal too long Explanation: Strings cannot be longer than 255 characters. Action: Edit the string. Text string or ordinal expected in control Explanation: A text string can be specified in the DIALOG statement of a dialog template to give it a title. If a title is not required, double quotation marks must be used with no characters between them (" "). Action: Edit DIALOG statement. Unbalanced parentheses Explanation: The left and right parentheses have not been matched. Action: Edit the parentheses. Undefined keyword or key name Explanation: An invalid keyword or key name has been used. Action: Check syntax. Unexpected end of file in string literal Explanation: The double quotation marks have not been closed at the end of a character string. Action: Edit the string. Unexpected value in RCData Explanation: The variable defined in RCData must be a string or a number. Action: Check the RCData syntax. Unknown dialog or window token Explanation: The dialog and window templates must use only the DIALOG, WINDOW, or CONTROL keywords. Action: Check the dialog or window template syntax. Unknown menu subtype Explanation: Items within a menu can be specified only with the MENUITEM and SUBMENU keywords. Action: Check menu definition syntax. ΓòÉΓòÉΓòÉ 17. T Terminal Emulator ΓòÉΓòÉΓòÉ Select One: Introduction and Help Command-Line Syntax Command-Line Options Terminal Setup Sending Files Pausing and Scrolling Receiving Files ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Introduction ΓòÉΓòÉΓòÉ The Kernel Debugger uses the T Terminal Emulator to communicate with the machine to to be debugged, also known as the MUT (Machine Under Test). You can also use T or to send and receive ASCII files. All functions of T are listed on the Help menu. Press F1 to view the Help menu, pictured below. TERMINAL - OS/2 ASCII Terminal Program Version 2.00.00 F1 or ALT-H Help F2 Terminal Setup F3 Send a file F4 Pause and Scroll F5 Toggle file capture F6 File capture control F8 or ALT-X Exit terminal program You must press Escape to exit this screen before continuing with any other functions. ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Command-Line Options ΓòÉΓòÉΓòÉ Use command line options when invoking T to specify the sceen size and the COM port to be used: -L[ines]X Where x = {25, 43, 50} -C[om]N Where n = {1,2,3} -? To display these options ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Command-Line Syntax ΓòÉΓòÉΓòÉ To display help for command-line syntax, type T -? at the prompt. OS/2* Terminal program Version 2.00.00 November 1st, 1991 Valid command line switches: -L[ines]X X={lines} -C[om]N N={1..8} -Q[uiet] enter quiet mode -V[tp]:name name=vtp server -S[end]:name name=auto-send file name -R[emark]:text text=status line remark (20 chars max) ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Terminal Setup ΓòÉΓòÉΓòÉ All terminal setup functions are listed here. Press F2 from the program's main screen to view the Terminal Setup menu. The Terminal Setup Options are as follows: o Help (press F1) o Port setup (Press F2) o Terminal emulation (Press F3) o Keyboard macros (Press F4) o Bells & Whistles (Press F5) o Exit setup mode (Press Esc or F8) You must press Esc to return to the main screen before continuing with any functions other than the above setup functions. ΓòÉΓòÉΓòÉ <hidden> T Term. Emul. - Setup Terminal Emulation ΓòÉΓòÉΓòÉ To set up terminal emulation, follow these steps: 1. Press F2 at the main screen. The Terminal Setup dialog will be displayed. 2. Press F3. The Terminal Emulation Setup dialog will be displayed. Terminal Emulation Setup Emulator status: None loaded. Help: F1 Z19 emulator: F2 Exit emulator setup mode: Esc, F8 ΓòÉΓòÉΓòÉ <hidden> T Term. Emul. - Setup Bells & Whistles ΓòÉΓòÉΓòÉ To change bells and whistles, follow these steps: 1. Press F2 at the main screen. The Terminal Setup dialog will be displayed. 2. Press F5. The Bells & Whistles Setup dialog will be displayed. 3. Make your selections. Bells and Whistles Setup Filter NULL characters: Yes Disable beeps: No Background: Foreground: Normal screen: Black White Status line: Blue Bright White Scroll screen: Blue Red Scroll status line: White Blue Help screen: Blue Bright White Menu: Blue Bright White Menu highlight: Cyan Black Next Value: ΓòÉΓòÉΓòÉ <hidden> T Term. Emul. - Setting Communications Parameters ΓòÉΓòÉΓòÉ To change communications parameters, follow these steps: 1. Press F2 at the main screen. The Terminal Setup dialog will be displayed. 2. Press F2. The Current COM2 Port Parameters dialog will be displayed. Current COM2 Port parameters: Baud Rate: 9600 Parity: NONE Data Bits: 8 Stop Bits: 1 Write Timeout (sec.): 1.00 Read Timeout (sec.): 0.10 Handshaking: XON/XOFF Next Value: -> Previous Value: <- Next Field: Dn Previous Field: Up Don't Change: Esc Accept Changes: Enter 3. Use the Up Arrow and Down Arrow cursor keys to scroll backward and forward through the parameter list, and the -> and <- keys to scroll through allowable values for each parameter. 4. Press Escape to exit this dialog without changing values, or press Enter to save these values and exit the dialog. Note: The communications port may be changed from the command line by using the -c option. ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Sending Files ΓòÉΓòÉΓòÉ To send a file, follow these steps: 1. Press F3. The Send File Control dialog will be displayed. Send File Control Send file name: SEND.TXT Don't send file: Esc Accept changes and send file: Enter 2. Enter the filename in the Send File name field. 3. Press Enter to send the file and exit the dialog, or press Escape to exit this dialog without sending a file. ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Pausing and Scrolling ΓòÉΓòÉΓòÉ To enter Scroll Mode and pause display of communications, follow these steps: 1. Press F4. A status line will appear at the bottom of the screen. F1=Help ESC=Active mode Screen Top is 100% through the buffer. Scroll Mode 2. Press F1 to display the Scroll Mode commands. Screen Scroll Mode F1 or ALT-H Help Dn Down a line Up Up a line PgUp Up a page PgDn Down a page ESC or Enter Return to active mode 3. Select a scroll mode command. ΓòÉΓòÉΓòÉ <hidden> T Terminal Emulator - Receiving Files ΓòÉΓòÉΓòÉ To receive a file, follow these steps: 1. Press F6. The Capture File Control dialog will be displayed. Capture File Control Capture file name: Capture.Txt Capture entire buffer: F3 START Capture: F5 Delete file: F9 Don't Change: Esc Accept Changes: Enter 2. Select an item from the Capture File Control menu. ΓòÉΓòÉΓòÉ 18. Workplace Class List ΓòÉΓòÉΓòÉ Select one: Introduction Starting Create an Instance Replace an Object Unreplace an Object Add an Object Delete an Object Class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Introduction ΓòÉΓòÉΓòÉ The workplace class list is a tool that creates a workplace object class and an instance of a workplace object class. Workplace objects are constructed using the SOM protocol and are instances of one of the following workplace object classes: Predefined These classes are defined by the system. Examples of predefined workplace object classes are WPObject, WPFileSys, and WPAbstract. Subclass These classes are derived from existing predefined workplace object classes. They add or remove function; however, they retain the basic behavior of that class. Replaced These classes replace the class being subclassed. They modify the behavior of an instance of a predefined workplace object class without the instance being aware of the new class. ΓòÉΓòÉΓòÉ <hidden> WP Class List - Starting Workplace Class List ΓòÉΓòÉΓòÉ To start Workplace Class List, select the PM Development Tools folder, then select Workplace Class List. A window appears. The window contains a list of the workplace object classes currently registered in the OS/2 Workplace Shell. Using the window, you can: o Create an instance of a workplace object class o Replace a workplace object class o Unreplace a workplace object class o Add a workplace object class o Delete a workplace object class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Create an Object Class Instance ΓòÉΓòÉΓòÉ To create an instance of a workplace object class: 1. Select the class from the list on the workplace object class window. 2. Display the pop-up menu by single-clicking mouse button 2. 3. Select the Create Instance choice. 4. Fill-in the following input fields: Object Title, Class of new object, Parameters, and Location. Note: Only an instance of a physical workplace object class can be created. In other words, you cannot use WPObject or WPClass because they are not physical classes. Input Fields Object Title is the text string you assign the object. The text string becomes the object title and appears under the object when the object is displayed on the Workplace Shell. When the object is in an opened state, the text string appears in the title bar of the window. Class of new object is the name of the class of which the object you selected is a member. Parameters is a series of keyname=value pairs (separated by semicolons) that change the behavior of the object. Each object class defines the keynames and parameters it expects to see. All parameters have safe defaults, so it is never required to pass parameters to an object. Location is a real name specified by a fully qualified file specification, such as C:\OS2\DLL\MINXOBJ.DLL, or a logical name specified by a predefined symbol. Examples of logical names include the following: LOCATION_NOWHERE The hidden folder LOCATION_DESKTOP The OS/2 desktop (Workplace) LOCATION_SYSTEM The OS/2 system folder LOCATION_TEMPLATES The template folder LOCATION_SYSTEMSETUP The system setup folder LOCATION_STARTUP The startup folder LOCATION_INFORMATION The information folder LOCATION_INFORMATION The information folder LOCATION_DRIVES The drives folder Related Information: o Replace a workplace object class o Unreplace a workplace object class o Add a workplace object class o Delete a workplace object class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Replace a Workplace Object Class ΓòÉΓòÉΓòÉ To replace an existing registered class: 1. Select the class from the list on the workplace object class window. 2. Display the pop-up menu by single-clicking mouse button 2. 3. Select the Replace choice. Note that only classes that have already been registered are valid. 4. Fill-in the following input fields: Original class and Replacement class. Note: The replacement class must be a descendant of the original class. Replacing an object class is useful for modifying the behavior of objects which are instances of the original class but are not aware of the replacement class. Input Fields Original class is the name of the object class being replaced in the Workplace. Replacement class if the name of the object class replacing the original class. Related Information: o Create an instance of a workplace object class o Unreplace a workplace object class o Add a workplace object class o Delete a workplace object class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Unreplace a Workplace Object Class ΓòÉΓòÉΓòÉ To return a replaced class to its original class: 1. Select the replaced class from the list on the workplace object class window. 2. Display the pop-up menu by single-clicking mouse button 2. 3. Select the Unreplace choice. Note that only classes that have already been replaced are valid. 4. Fill-in the following input fields: Original class and Replacement class. Input Fields Original class is the name of the replaced object class being returned to its original object class in the Workplace. Replacement class if the name of the replaced object class being returned to its original object class. Related Information: o Create an instance of a workplace object class o Replace a workplace object class o Add a workplace object class o Delete a workplace object class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Add a Workplace Object Class ΓòÉΓòÉΓòÉ To add a class to the Workplace Shell: 1. Display the pop-up menu by single-clicking mouse button 2. 2. Select the Add Class choice. 3. Fill-in the following input fields: New class name and Library module. Input Fields New class name is the name of object class you want to add to the Workplace. Type the class name exactly as it is built, case sensitive. Library module is the name of the dynamic link library (DLL) that holds the object definition. Type the library name with complete file specification information. Note: The DLL must be created by the IBM System Object Model. Related Information: o Create an instance of a workplace object class o Replace a workplace object class o Unreplace a workplace object class o Delete a workplace object class ΓòÉΓòÉΓòÉ <hidden> WP Class List - Delete an Object Class ΓòÉΓòÉΓòÉ To delete a class from the Workplace Shell: 1. Select the class you want to delete from the list on the workplace object class window. 2. Display the pop-up menu by single-clicking mouse button 2. 3. Select the Delete a Class choice. 4. Fill-in the name of the class you want to delete from the Workplace. Note: You cannot delete system predefined classes. For example, WPObject or WPClass. Related Information: o Create an instance of a workplace object class o Replace a workplace object class o Unreplace a workplace object class o Add a workplace object class