═══ 1. Special Notices ═══ Second Edition (July 1994) This edition applies to Version 2.1 of IBM* WorkFrame/2* (Program number 82G-3734). Make sure you are using the correct edition for the level of the product you are using. Any reference to an IBM licensed program in this help is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent product, program, or service that does not infringe on any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. This document may contain examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples may include names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. The following terms, denoted by an asterisk (*) in this document, are trademarks of the IBM corporation in the United States and/or other countries: WorkFrame/2 C Set ++ IBM OS/2 Operating System/2 Presentation Manager WorkPlace Shell ═══ 1.1. Copyright Notice ═══ Integration Kit for IBM* WorkFrame/2* Version 2.1 The integration kit contains an information reference and sample programs illustrating application programming interfaces to provide assistance with product integration into IBM's WorkFrame/2 Version 2.1. The information and sample programs are intended only for Version 2.1, and are not applicable to any other IBM product or product release. The integration kit is provided as is, without any warranty of merchantibility of fitness for any particular purpose. The kit includes sample code. This code has not been tested, and IBM makes no representation of its workability or fitness on any system. You are permitted to make copies of the whole of this kit, including this notice screen. You are also permitted to copy the sample programs, and their source, contained in the kit for the purpose of running those programs on your system. You may distribute copies of the whole of this kit, or only of the sample programs, in any country recognising the copyright of U.S. nationals. Any copies distributed by you must include a copy of this notice screen. IBM will attempt to make future releases of the WorkFrame/2 product compatible, but cannot guarantee upward compatibility. (c) Copyright International Business Machines Corporation 1994. ═══ 1.2. Reader's Comments ═══ Missing items are flagged with a "@@@" symbol. Please address questions and comments to: Angelique F. Faustino FAUSTINO AT TOROLAB4 faustino@torolab4.vnet.ibm.com Tie line 778-3297 Help on using the WorkFrame/2 product is available through: o External support channels: 1. CompuServe: OS2DF1 forum 2. Internet: WorkFrame@vnet.ibm.com o Internal support channels: 1. VNET: TOROLAB6(WF2SUPP) 2. WRKFRAME FORUM and WRKFRAME CFORUM on the IBMPC disk Important note: Please do not post integration questions on the public forums. Instead, e-mail to the Internet or VNET address given above. ═══ 2. ------------------------------------------------------- ═══ ═══ 3. User's Guide ═══ ═══ 4. ------------------------------------------------------- ═══ ═══ 5. Introduction ═══ This online reference describes the WorkFrame/2* V2.1 C Integration Toolkit, a set of application programming interfaces (API's) for integrating tools and file systems with the WorkFrame/2 version 2.1 programming environment. The categories of WorkFrame/2 Integration Toolkit API's can be divided into two groups: 1. WorkFrame/2-provided APIs: Actions Profile Message Routing Projects Installation Support 2. APIs to be provided by tool integrators: Action Support Project Access Method (PAM) Any mention of WorkFrame/2 hereafter refers to Version 2.1 of the WorkFrame/2 product, unless explicitly qualified. ═══ 5.1. Who Should Use This Book ═══ This document is a detailed technical guide and reference for application programmers who are knowledgeable in C and Presentation Manager* (PM) programming, and want to build applications to work seamlessly within the WorkFrame/2* environment. Basic knowledge of SOM is also useful. This document assumes a good understanding of WorkFrame/2 Version 2.1 features and terminology from a user's perspective. The WorkFrame/2 Integration Toolkit provides API's to: 1. Integrate programming tools like compilers, linkers, debuggers, and editors, and other general-purpose tools, into the WorkFrame/2 environment. 2. Access project objects from remote file systems other than OS/2*. 3. Set up and interact with project objects and actions. ═══ 5.2. How to Use this Book ═══ This document is divided into two main parts. The first part is a guide that explains concepts, and describes the components of this Integration Toolkit. The second part is a reference to the WorkFrame/2* data types, APIs, and messages. Read the material under the overview and introduction headings to get an overall view of how to integrate with the WorkFrame/2 product. Read the reference material to understand how each API works. The WorkFrame/2 Integration Toolkit APIs are divided into five categories. These categories are reflected as first-level headings in the reference part of this document. There is more detailed information about each category under their headings. APIs are presented in the table of contents in an order that is most beneficial to the reader who views each API in sequence. The order is not alphabetical, but can be viewed alphabetically in the index of this document. Callback functions and macros are described first, and then the APIs in the order that they will most likely be used. ═══ 5.2.1. Conventions Used in this Reference ═══ Fonts Used in this Reference In this reference, code fragments appear in a monospaced font. WorkFrame/2* API names appear in boldface. Publication names appear in underlined italics. New terms are italicized. Hypertext links are shown in a different colour from the rest of the text. Conventions Used in Function Descriptions The purpose of this online document is to provide information about the WorkFrame/2* Version 2.1 Integration functions, parameters, return codes, data types, variables, and constants. This section provides information about the notation conventions and function descriptions used in this reference. Each function is described with the following: Function Syntax Describes the C language calling syntax of each WorkFrame/2-provided function. Integrator-provided functions are typedef'd as pointers to functions. The typedef declarations are shown. Parameters Each parameter is listed with its C language data type, parameter type, and a brief description. o Data types All OS/2* and WorkFrame/2* data types are written in uppercase. When a WorkFrame/2-defined data type is used, a hypertext link is provided to its definition. WorkFrame/2-defined data types are prefixed with "WKF". A data type of "Pxxxx" implicitly defines a pointer to the data type "xxxx". o Kinds of Parameters There are three kinds of parameters: Input Specified by the caller Output Returned by the function Input/Output Specified by the caller and modified by the function. o A brief description of each parameter is given. Where appropriate, restrictions and prerequisites are also included. In many cases, the parameter is a pointer to a structure or string buffer. Return Values A list of possible return codes is provided. A function of type ULONG returns a zero (NO_ERROR) or a WorkFrame/2-defined return code. A function of type APIRET returns zero, or an OS/2-defined return code that is less than the constant ERROR_USER_DEFINED_BAS. These return codes result from a call to an OS/2 API within the function. APIRET return codes greater than ERROR_USER_DEFINED_BAS are WorkFrame/2-defined. Example Each function has a C language example showing how it could be used. Programming Note The functions in this document are named in mixed-case for readability, but are known to the WorkFrame/2 program as uppercase character strings. If you are using a compiler that generates a mixed-case external name, you should code the functions in uppercase. ═══ 5.2.2. Related Documentation ═══ If you are not familiar with the WorkFrame/2* Version 2.1 product and terminology, please refer to the following publications: o Online WorkFrame/2 Tutorial o IBM C/C++ Tools: WorkFrame/2 Introduction (publication number S82G-3740) o Online help If you need information on Presentation Manager* programming, see the following publications: o Online PM Reference from IBM Developer's Tookit o Publications from the OS/2 Developer's Toolkit Technical Library (number SBOF-1206), especially: - OS/2 2.0 Application Design Guide (S10G-6260) - OS/2 2.0 Programming Guide Volumes I, II, and III (S10G-6261, S10G-6494, S10G-6495) - PM Programming Reference Volumes I, II, and III (S10G-6264, S10G-6265, S10G-6272) - OS/2 2.0 Control Program Programming Reference (S10G-6263) o Designing OS/2 Applications by David E. Reich (publication number SC28-2701) o Advanced OS/2 Presentation Manager Programming by T.E. Burge and J. Celi Jr. (publication number SR28-4646-0) For information on SOM programming, refer to the following IBM* publications: o Online SOM Reference from IBM Developer's Toolkit o OS/2 2.0 System Object Model Reference (S10G-6309) ═══ 6. Overview of the WorkFrame/2 Integration Toolkit ═══ IBM* WorkFrame/2* Version 2.1 is a unique, object-oriented application development framework that takes full advantage of the OS/2* Workplace Shell* environment to create a highly-customizable graphical interface that simplifies the process of organizing and building software projects. You can integrate any DOS, Windows*, and OS/2 16- and 32-bit tools within the WorkFrame/2 environment in a seamless fashion using the APIs provided in the WorkFrame/2 Integration Toolkit for Version 2.1. This section briefly introduces the groups of APIs that make up the WorkFrame/2 Integration Toolkit, and explains some of their key concepts. Projects APIs for reading and writing to base project file. Creating and setting projects is also discussed. Action Support APIs for providing an Options DLL to display and set tool options, support make file creation, and provide error handling and context-sensitive help for tool error messages. Project Access Method (PAM) APIs for providing a project access method to enable one or more WorkFrame/2 projects to consist of parts from a remote system or from a file system other than OS/2. Actions Profile APIs for querying actions, environment variables, and available types. Creating and setting actions profiles is also discussed. Message Routing APIs for communicating with the router to send and receive notification messages from other registered tools. ═══ 6.1. What the Integration Toolkit Includes ═══ Included in the WorkFrame/2* Version 2.1 Integration Toolkit are: Public header (.H) files WKF.H, WKFINS.H, WKFMSG.H, WKFOPT.H, WKFPAM.H, WKFPRF.H, WKFPRJ.H Containing type definitions, variable and constant declarations (including WorkFrame/2-defined message classes), and function prototypes that define the entrypoints to dynamic link libraries (DLLs) provided both by this toolkit, and by tool integrators. Import library (.LIB) files WKF21.LIB, WKFBPM21.LIB, WKFDEF21.LIB Containing library code that calls the WorkFrame/2-provided APIs. These should be statically linked with integrating applications. Dynamic Link Library (.DLL) files Containing library code for the WorkFrame/2-provided APIs. These are shipped with the WorkFrame/2 Version 2.1 product and are not explicitly included with this Integration Toolkit. Sample Programs A number of sample programs are provided to illustrate the use and definition of the WorkFrame/2 Integration APIs. Integration Toolkit Reference (this document) Describes the process of integrating tools into the WorkFrame/2 Version 2.1 environment, and the APIs required to accomplish this. ═══ 6.2. About the WorkFrame/2 Integration Toolkit APIs ═══ The WorkFrame/2* Integration Toolkit is a set of functions you need to fully enable your tool for use within the WorkFrame/2 version 2.1 environment. Most of the APIs are provided by this Integration Kit for your use (these are referred to as WorkFrame/2-provided APIs). These include the Project, Actions Profile, Message Routing, and Installation Support APIs. Other APIs must be supplied by the tool-integrator as DLL entrypoints that enable the WorkFrame/2 program to obtain important information about your tool. In this document, the Action Support APIs are referred to as integrator-provided; and the PAM entrypoints as PAM-provided. In particular, you must provide a defined set of action support and/or PAM APIs in a dynamic link library (DLL) if you want to: 1. Present a customized graphical user-interface to the user for setting tool options. 2. Provide a project access method (PAM) to access project parts on a foreign (non-OS/2) or remote file system, or to customize access to project parts. This document does not give you a detailed description of how you should write the APIs, since that depends on the nature of your tool, the file system you are using, and how you want to control interaction with the user. However, this document does tell you: 1. How the WorkFrame/2 will call your API 2. The minimum tasks your API must perform to successfully integrate with the WorkFrame/2. ═══ 6.2.1. Creating DLLs for Integrator-supplied APIs ═══ The integrator- and PAM- supplied APIs must be made available to the WorkFrame/2* program as entrypoints in a dynamic link library (DLL). The following is a list of requirements for building the DLLs: 1. Write the code for all the required entrypoints as defined in the header files. These entrypoints are described later in this document. 2. Compile the APIs into a DLL. Note that actions support for multiple tools, including a single PAM, can be contained in the same DLL. Suites of related tools that may or may not need a specialized project access method can provide a single WorkFrame/2-integrating DLL. The name of the DLL which contains your APIs for handling tool options is specified in the Options page of the actions profile's Settings notebook for your tool's action entry. The name of the DLL which contains your PAM APIs is specified in the Access page of the Settings notebook of the project that needs to use your PAM. When the WorkFrame/2 needs to call an API for your tool, say, when the user wants to change the options settings, WorkFrame/2 looks in the actions profile for your tool to obtain the name of the DLL it needs to load. Similarly, WorkFrame/2 obtains the name of the PAM DLL from the project settings when, for example, the user wants to edit a project object that resides on another file system. Note that the following default options and PAM DLLs are provided with the WorkFrame/2 product: DDE3DEF2.DLL (Default Options DLL) Provides an options dialog that allows users to enter command-line options for any tool. DDE3BPAM.DLL (Basic Project Access Method) Provides basic access to local and LAN-based OS/2 file system objects that can exist in multiple directories for a particular project. Related information: o Building Actions Support and PAM DLLs ═══ 6.2.2. Using the WorkFrame/2-provided APIs ═══ All WorkFrame/2* version 1.x interfaces are supported in version 2.x. The internal interface layer takes care of parameter conversions and API mappings between version 1.x and version 2.x interfaces. An important difference with the version 2.x interfaces is that they are consistent for all types of tools and actions, not just for compilers. All version 2.x and higher APIs are 32-bit and use the _System linkage convention. Specify the APIENTRY linkage keyword in function declarations when providing interfaces to the WorkFrame/2 program. ═══ 6.3. About the Sample Programs ═══ The WorkFrame/2* Integration Toolkit provides a collection of sample programs to illustrate certain aspects of WorkFrame/2 integration: Install Installs a WorkFrame/2-integrated tool called Sample. It illustrates: 1. Detecting the installed version of the WorkFrame/2 program. 2. Detecting the installed WorkFrame/2 folder location 3. Creating a tool or product folder 4. Creating a sample actions profile 5. Adding an entry in the actions profile 6. Creating a project that uses the actions profile 7. Setting project options for the tool. To use this tool, run INSTALL.EXE. It creates a folder on your desktop that contains a sample actions profile and project. Launch Launches any action, by name or by class, from any other tool. It illustrates: 1. Integrating a vio (non-PM) program into the WorkFrame/2 router 2. Launching an action, by class or by name, for a specific project from an external tool. To use this tool, run LAUNCH.EXE with the following command line: launch You can also run the TEST.CMD file, which demonstrates launching a COMPILE action on the Hello World WorkFrame/2 sample. PeterPAM A project access method that displays different icons depending on project part file name extensions. It illustrates chaining to the default PAM, DDE3DEF2.DLL. To use PeterPAM, copy PETERPAM.DLL to a directory on your LIBPATH, such as the \DLL subdirectory of your WorkFrame/2 installation directory. Specify "PETERPAM" as the access method for a project. To associate icons with file extensions, select the Options pushbutton on the Access page of the project's Settings notebook. The project's container view should then display the project files with the associated icons. SOMOpt An actions support (Options) DLL for the SOM compiler. It illustrates providing actions support for a tool. To use this tool, create an action for the OS/2 SOM compiler, and have it use SOMOPT for its Options DLL. Set SOM compiler options for a project and try to create a make file involving the SOM compiler action to see how the DLL generates dependency information for MakeMake. The SOMOPT.DLL contains all the required entrypoints for an actions support DLL. WFPeek - Router Peek and Display Displays WorkFrame/2 router messages. It illustrates: 1. Integrating a Presentation Manager* program into the WorkFrame/2 router 2. Receiving messages from the WorkFrame/2 router To use WFPeek, run WFPEEK.EXE then perform certain actions that would generate a router broadcast to registered clients, such as an update to a project or actions profile. The notification messages are shown in the WFPeek window. WKFInfo Displays public information about a project and its available actions. It illustrates: 1. Using the project APIs for reading the project file to display public project information 2. Using the actions profile APIs for querying the project's available actions and displaying information about them. To use the WKFInfo sample, run WKFINFO.EXE and select a project file. Information about the project is displayed on the WKFInfo window. WFEdit A WorkFrame/2-integrated simple editor. It illustrates the editor side of the Dynamic Data Exchange (DDE) protocols used within WorkFrame/2 To run this sample editor, add it as the default EDIT-class action for a test project, and specifying the default Options DLL, DDE3DEF2, for the WFEdit action. Ensure that the Send errors to editor checkbox is selected for the project's WFEdit options. Run a monitored action, such as a COMPILE or MAKE, on a project with a source file that contains an error so that an error message is output to the Monitor. Double-click on the error text in the Monitor window to invoke the default editor and begin the DDE session. The editor displays the DDE messages as they are received, and the values of certain variables. QStart Creates projects from the command line. It illustrates the ease at which projects can be created. To use this tool, run QSTART.EXE to create a project with the default values on the desktop. Use the command line options (documented in the QSTART.CMD file) to override default values. ═══ 6.4. Overview of the API Categories ═══ This section gives a brief overview of each WorkFrame/2 Integration Toolkit API category: Projects Action Support Project Access Method (PAM) Actions Profile Message Routing Installation Support ═══ 6.4.1. Projects ═══ ═══ Dummy ═══ ═══ Dummy ═══ WorkFrame/2* projects offer a way to organize the development of your software application into different components. For example, the components of a software application could consist of an executable file, a dynamic link library, and a class library. Within the WorkFrame/2 environment, these components are referred to as base projects. Projects are managed by the WorkFrame/2 Project Manager. A project visually appears as a Workplace Shell container that holds the source code objects for a particular component. These source code objects are called project parts. Projects also contain important information used to build the component, such as tool option settings and a make file. Composite projects are containers that can hold base projects and other composite projects. The open WorkFrame/2 project interface offers minimal data integration with WorkFrame/2 so that tool-specific project information can be saved and retrieved without affecting other integrating tools. Through this set of APIs, tool integrators can enable tools to: o Create projects o Query or modify project settings Tools that ship sample code can use these APIs to create their own projects and project settings. ═══ 6.4.2. Actions Support ═══ ═══ Dummy ═══ ═══ Dummy ═══ The Action Support APIs give your tool the ability to allow a user to specify options through customized graphical user interface, such as a dialog or notebook, that is fully integrated with the WorkFrame/2* interface. An example is the C Set ++* compiler options dialog provided by the DDE4ICC options DLL. It lets you set options for the C Set ++ Compile action (in the IBM C/C++ Tools Actions Profile) for a project via a settings notebook that divides groups of compile options into pages. Options settings can be stored with a particular project, thus giving each project its own set of options that apply each time the tool is invoked on its behalf. Within the WorkFrame/2 environment, a tool is presented to the user as an action defined in an actions profile. When the action is invoked via the WorkFrame/2 object-action method, WorkFrame/2 automatically builds an invocation string from the options that were set and uses it to invoke the tool. To allow users to set options for your tool via a graphical user-interface, you will need to provide the proper function entrypoints and externalize these as APIs in a dynamic link library (DLL). The WorkFrame/2 program calls these functions to get information about your tool (such as its default options settings and error handling). When your tool is set up as a WorkFrame/2 action, the name of the Options DLL to use for querying and setting options is specified in the Options page of the action's Change Action notebook accessed from the actions profile. Because you write the code for the APIs, you can design your options-setting interface so that the interaction with the user is best suited to the nature of your tool. The APIs you will need to provide are defined later in the WorkFrame/2 Integration Toolkit reference guide. The WorkFrame/2 program calls these APIs to: o Display and set options for the action o Retrieve the command line to execute for the action o Support make file creation o Provide error handling and context-sensitive help. The kinds of tools that might be interested in providing their own Options DLL are: o Compilers o Browsers o Source librarians o Editors o Linkers o Make tools o Any tools with many command-line options. Note that support for multiple tools can be provided in a single DLL. ═══ 6.4.3. Project Access Method (PAM) ═══ ═══ Dummy ═══ ═══ Dummy ═══ A Project Access Method (PAM) is the mechanism through which project parts are accessed. It is a pluggable layer that abstracts underlying system details from the WorkFrame/2* Project Manager. The functions that accomplish this are located in a dynamic link library (DLL). When a user wants to use a project access method other than the one supplied with WorkFrame/2, the PAM's DLL is specified on the Access page of the base project's Settings notebook. By default, the PAM for a base project is the Basic Project Access Method (bPAM) provided with WorkFrame/2. This PAM allows project files to exist in multiple OS/2* directories on both local and LAN attached servers. This basic PAM uses standard OS/2 APIs to access files. There are many reasons why you might want to provide your own PAM: 1. To allow project objects that reside on remote systems to be accessed in the same manner as locally defined objects. The method of communication with the remote system is soley determined by the PAM. 2. To seamlessly launch actions on remote systems. 3. To mix multiple systems on one OS/2* desktop. 4. To mix objects from multiple systems on a single project. 5. To customize access to project parts. For example, if you want projects parts to be displayed sorted by date or name, or in a specialized view. 6. To seamlessly integrate source librarians for version control. To create your own PAM, you will need to provide the logic for the functions described later in this document. You can also modify the behavior of existing PAMs by chaining with one or more other PAMs. Chaining your PAM with other PAMs enables any project that specifies your PAM to access objects from the remote systems specified by the other PAMs. Since you can specify only one PAM for a project, all PAMs must, at minimum, provide the same support for OS/2 files as the basic PAM (bPAM) that comed with the WorkFrame/2 product. This can be easily accomplished by chaining your PAM with the bBPAM DLL. See How to Create a PAM for more information on how to create and chain PAMs. Following are some kinds of tools that could integrate with the WorkFrame/2 program by providing their own PAMs: o Source librarians o Client-server enablement tools o Tools that run on a different file system than OS/2 o Tools that reside on a remote file system o Source databases o Project view containers ═══ 6.4.4. Actions Profile ═══ ═══ Dummy ═══ ═══ Dummy ═══ An actions profile defines the set of functional services that are available to a project. It contains a set of actions that can be associated with one or more projects. An action is a command that is performed on an object. An object may be an entire project, a composite project, or a file object like a .C file. A special actions profile, the Default Actions Profile (DAP), defines the actions that are available to all projects. The concept of an action treats all tools equally, whether they are compilers, editors, linkers, formatters, browsers, debuggers, icon editors, or preprocessors. A project may have access to several languages because any number of compilers and tools can be added to an actions profile. Any action in an actions profile can be input to the MakeMake make file generator. Actions profiles make it easy to group any number of tools for use by a specific set of projects or by all projects. The API set provided by WorkFrame/2 for actions profiles lets you o Create a custom actions profile for your set of tools that can reside anywhere in the system o Add your tool as an action within a profile o Query and modify existing profiles Some kinds of tools that could take advantage of the capabilities offered by the actions profiles API set are: o Source librarians o Full-function code editors o Compilers o Program builders o Make tools o Suites of tools that work together. ═══ 6.4.5. Router ═══ ═══ Dummy ═══ ═══ Dummy ═══ Full integration between objects and tools (actions) within the WorkFrame/2* environment is facilitated by the WorkFrame/2 router. It enables tool-to-tool, object-to-object, and tool-to-object communication. The WorkFrame/2 router accomplishes this by serving as a message abstraction layer and integration point between WorkFrame/2 objects, tools, and other messaging facilities such as BMS (Broadcast Message Services). It also manages communication with the WorkFrame/2* Action Log. The router integrates any kind of tool that OS/2* supports, including OS/2 tools that run under: o VIO o Presentation Manager* o Workplace Shell* DOS and WIN-OS/2 programs cannot integrate with the router. Objects that are registered for communication with the WorkFrame/2 router are called clients. The router broadcasts the messages that it receives from registered clients to other interested clients. Clients specify the types of clients whose messages they are interested in when they register with the router using the WkfInitialize API. For example, a compiler could send a WKFM_FILECHANGED message to the router when it creates or updates an executable file. The router would then broadcast this message to interested clients, among which would be the base project to which the changed file belongs. The base project could then update its view to reflect the changes made to the file. Currently, up to 320 tools can be concurrently integrated into the router. Some of the services the router provides are: 1. Sending notification messages from any router client. Examples are: o Changes to a base project o Changes to a project file o Actions profile changes 2. Facilitating communication between tools 3. Launching actions within the context of a project. 4. Posting entries in the WorkFrame/2 Action Log. Note that some messages are echoed to the Action Log at the WorkFrame/2 program's discretion, without explicit instructions from the sender to do so. Some kinds of tools that would benefit from the router services are: o Source librarians or versioning tools o Compilers o Program builders o Make tools o Make file generation tools o Browsers o Any development tools that operate against files or projects o Suites of tools that work together. ═══ 6.4.6. Installation Support ═══ ═══ Dummy ═══ ═══ Dummy ═══ The integration support APIs are provided to help tool integrators perform the tasks necessary to install WorkFrame/2 support for their tools. Two APIs are provided. One detects if the requested version of WorkFrame/2 is installed in the system, and returns the installation path. Tool integrators can then choose to install WorkFrame/2 support only if WorkFrame/2 is installed on the system. The other API sets the default options for tools that use the default actions support (Options) DLL, DDE3DEF2. This is a convenience for tool integrators who are not providing their own actions support DLL. ═══ 7. Overview of the WorkFrame/2 Architecture ═══ ═══ Dummy ═══ The WorkFrame/2* architecture consists of independent components that interact with each other through APIs and router messages. Below is an illustration of the general WorkFrame/2 architecture: ═══ Dummy ═══ ═══ Dummy ═══ The numerical labels on the diagram shows the important interactions between WorkFrame/2 components: 1. Display and set tool options 2. Launch action 3. Get invocation string 4. Start a tool or action 5. Display tool output ═══ 8. Integration Tips ═══ There are a number of points to consider when integrating a tool with the WorkFrame/2* program: 1. The tool should be project-aware. This involves: o Using the project interfaces to query project data and store tool-specific data associated with projects o Using the PAM interfaces to query files o Using the action support interfaces to query or launch actions. 2. The tool should register with the router when it is invoked, and deregister when it is closed. The tool should send router messages whenever a relevant event occurs. 3. The actions profile should be viewed as the single point of all tool integration. Your tool should be visible to the user as an action, and be consistent with the concept of an action in the WorkFrame/2 program. 4. When the tool is being installed, it is good practice to: o Verify whether WorkFrame/2 has been installed on the system, and that it is the correct version. o Create actions for all the tools being installed. You can also create a separate actions profile to hold all the new actions for your tools. o Create working sample projects for your tools that use your Project Access Method (PAM) or the default bPAM. o Provide an actions support DLL and specify the Options DLL name for each action you create. o You may wish to install some of your tools in a C Set ++* folder, or update a WorkFrame/2 object, such as the Default Actions Profile. See Persistent Object IDs for a list of WorkFrame/2 and useful object IDs. See the Install sample program for a demonstration on how you might accomplish the tasks required for an installation of your WorkFrame/2-integrated tool. 5. If your tool resides on a remote system or a system other than OS/2*, provide a Project Access Method (PAM) DLL to support the remote system. 6. Use the WorkFrame/2-defined constants when writing integrated code to help ensure upwards-compatibility with future releases. ═══ 9. ------------------------------------------------------- ═══ ═══ 10. Reference ═══ ═══ 11. ------------------------------------------------------- ═══ ═══ 12. Action Support ═══ This section gives instructions on how to create an options DLL for your tool, and describes, in detail, the function entrypoints you need to provide. ═══ 12.1. How to Create an Options DLL ═══ Provide an options DLL if you want to handle tool options in a customized manner, and if you want to display a customized graphical user-interface to accept options settings from the user. Below are instructions on creating an options DLL: 1. Include all the following required entrypoints (prototyped in the WKFOPT.H header file) in a single DLL. WkfQuery...Options WkfQuery...Target WkfQuery...Target Wkf...Terminate WkfQuery...ResourceID WkfQuery...HelpFile WkfQuery...ParseError WkfQuery...QueryDDE 2. Follow the Guidelines for Designing an Options Interface when designing your options dialog or notebook. 3. Provide only 32-bit interfaces that use the system linkage convention. 4. Use address parameters that contain flat memory addresses. 5. Handle errors by returning the appropriate OS/2*-defined return code from a call to an OS/2 Dos... API in your functions. If an error cannot be mapped to an equivalent OS/2 return code, return WKF_ERROR, as defined in the WKFOPT.H header file. 6. Name each entrypoint as defined in this document, replacing the ellipses with the tool's class name, and the entire name upper-cased. For example, if your tool is an editor (an action of class EDIT), define the entrypoint for WkfQuery...Options as WKFQUERYEDITOPTIONS(). Convert any spaces in the class name to underscores. ═══ 12.2. Guidelines for Designing an Options Interface ═══ It is often convenient to be able to set options from a graphical user-interface. Rather than having to remember cryptic command-line options like /G or /T, user can input values in entry fields with meaningful prompts and help support, and choose settings via radio buttons and check boxes. It might be helpful to look at the notebooks for setting options for the IBM* C Set ++* actions, like Compile, Link, and Browse, when designing your own. It is recommended that the WkfQuery...Options API display such an interface as part of its processing. The following are some guidelines to follow that will make the interface easy to use: 1. All dialogs and controls should conform to Common User Access* (CUA*) guidelines. For more information about the Common User Access guidelines, refer to the Common User Access: Guide to User Interface Design (order number SC34-4289) and the Common User Access: Advanced Interface Design Reference (order number SC26-4290). 2. If the number of options is large enough so that they cannot all fit in one dialog, use a notebook control to display pages of options, or a window containing pushbuttons corresponding to various categories of options. In the latter method, the user would select a pushbutton to display a modeless secondary window. By making the secondary window modeless, you can let the user see different groups of options at the same time. Design the interface so that closing the main window also closes all secondary windows. 3. Include the following pushbuttons: OK On a secondary window, selecting OK means the user is satisfied with the settings in the window and wants to close it. On the primary window, it means the user is finished setting options for the integrated tool and is ready to close the interface. If the OK pushbutton is pressed on the primary dialog but the user has not closed all the secondary windows, display an information message asking the user to close the secondary windows first. Default Sets the fields for all options to their default values. On a secondary window or notebook page, it sets only the options present on the page. The default values should correspond to those the tool would use if it were invoked outside of WorkFrame/2*. Reset (Optional) Resets all options to the values they had when the options interface was first opened. Pressing Reset has the same effect as pressing Cancel then opening the interface again. Cancel Closes the window without taking any other action. Settings are not saved. Help Provides help for the selected item or page. 4. The user may choose options that conflict with each other. Detect conflicts when the OK pushbutton is selected on the primary window, then display a window indicating what the conflicting options are, and let the user return to the interface to clarify the choices. ═══ 12.3. DDE Interaction with Editors ═══ The WorkFrame/2* program communicates errors from an invocation of a monitored action to integrating editors via DDE (Dynamic Data Interchange) calls. The following sequence of events illustrates the interaction between the invoked action, the WorkFrame/2 program, and the integrating editor. See the WFEdit sample program for a more complete illustration of how to implement the editor side of the WorkFrame/2 DDE protocols. Note: This section assumes that you are familiar with DDE (Dynamic Data Interchange) protocols. 1. In response to the user's request for a monitored action on a project or its parts, such as a make, compile, link, or build, the WorkFrame/2 program invokes the requested tool by invoking the WkfRun project access method API of the PAM DLL specified for the project. The output is then displayed in a listbox in the Monitor window. 2. When the user double-clicks on an error line in the Monitor (or selects a line and begins a drag operation) for the first time, WorkFrame/2 will invoke the WkfParse...Error entrypoint of the tool's actions support DLL to find the file in which the error occurs, and the list of displayed error messages that pertain to the same file. Only the error messages that occur in the current invocation of the action in the Monitor listbox are parsed. 3. The WkfParse...Error interface returns the parsed error information to WorkFrame/2, at which point WorkFrame/2 invokes the actions support interface WkfQuery...HelpFile to determine the name of the error message help file, if one exists. 4. The WorkFrame/2 program then starts the default editor (the default action for class EDIT) via DosStartSession passing it the name of the source file identified in the selected error message. The WorkFrame/2 program then issues a WinDDEInitiate call to establish a DDE conversation with the editor. Note that if a drag operation is in progress, WorkFrame/2 will instead issue a DrgDrag request, and if a drop is accepted, enable itself for DDE communication. Note: It is the editor's responsibility to ensure that only one edit session is open for the given source file. If an edit session is already open for the given file, it should be reused or terminated. 5. The editor should register itself as a server for the identified source file by likewise issuing a WinDDEInitiate call, specifying an application name of "WB Editor", and using the filename as the topic name. That is, WinDDEInitiate (hwndEditor, /* Editor window handle */ "WB Editor", /* Application name */ szFiletoEdit, /* Topic name - source file name */ NULL); /* Conversation context - not used */ Once the editor is initialized, it receives a connection request for the file via a WM_DDE_INITIATE message. The WorkFrame/2 window handle is sent in MP1 and a pointer to a DDEINIT OS/2-defined structure in MP2. The DDEINIT structure has this format: ULONG cb; /* Length of this structure */ PSZ pszAppName; /* Application name - "WB Editor" in this case */ PSZ pszTopic; /* Topic name - "Initialize" in this case */ ULONG offConvContext; /* Not used */ The editor should accept the request by issuing a WinDDERespond call. That is, PDDEINIT pddei; WinDDERespond ((HWND) mp1, /* From WM_DDE_INITIATE - WorkFrame/2 window handle */ hwnd, /* Editor's (server) window handle */ "WB Editor", /* Application name */ *(pddei->pszAppName), /* File to edit - topic name */ NULL); /* Conversation context - not used */ 6. Once WorkFrame/2 receives the acknowledgement, it sends a WM_DDE_EXECUTE "Initialize" message ("Initialize" is the topic of the message), passing the editor information about all the source lines in error, and the name of the error help file, if one exists. The editor may then perform preparatory tasks such as initializing variables to keep track of the original line numbers, highlighting all the lines in error, and enabling a help control. The WorkFrame/2 window handle is passed in MP1. The format of the message structure passed in MP2 is as follows: typedef struct _DDESTRUCT { ULONG cbData; /* Size of structure + topic name + data */ USHORT fsStatus; /* Ignore */ USHORT usFormat; /* Ignore */ USHORT offszItemName; /* Offset to message topic name */ USHORT offabData; /* Offset to beginning of data area */ } DDESTRUCT; The message topic name has this format: CHAR message[]; /* Contains "Initialize" in this case */ The data area has the following format: ULONG errorcount; /* Number of errors in errors[] buffer */ ERRSTR errors[]; /* List of source lines in error */ ULONG textlength; /* Length of libraryname[], not including terminating NULL */ char libraryname[]; /* ASCIIZ name of error help file */ Where ERRSTR is a structure that represents each error and consists of: ULONG errorline; /* Source line number containing error */ ULONG offset; /* Offset of error within the source line in error */ ULONG length; /* Highlight line starting at this offset; always zero for now */ ULONG magic_cookie; /* First line in Monitor window relating to error */ Note: Use the OS/2-provided helper macros, DDES_PSZITEMNAME and DDES_PABDATA, to obtain pointers to the data area and message topic name from their offsets, offszItemName and offabData, respectively. The WM_DDE_EXECUTE message also implies a WM_DDE_ADVICE message, confirming that the editor may send WM_DDE_DATA requests to WorkFrame/2. The magic_cookie field is the first line in the Monitor window that relates to the current message. The magiccookie value serves as an index to the error, and can be used in a WM_DDE_DATA "SendGoto" message from the editor to WorkFrame/2. (The "SendGoto" message is discussed below). This mechanism allows the editor to implement "Next error" and "Previous error" controls that allow the user to traverse through the list of errors in the source file. If the textlength field of the data area is not zero, then an error help file is available and given in the libraryname[] field. The editor should associate this help file with the current help instance. 7. After it has handled the WM_DDE_EXECUTE message, the editor should then send a WM_DDE_ACK message to WorkFrame/2 confirming acceptance to the command. WinDDEPostMsg (hwndWF, /* Client (WorkFrame) window handle */ hwnd, /* Editor's window handle */ WM_DDE_ACK, /* Message ID */ pddeIn, /* PDDESTRUCT - MP2 of WM_DDE_EXECUTE "Initialize" message */ TRUE); /* Options */ 8. At this point, the DDE converation is established and the editor is initialized for the source file. As the user continues to double-click on different error messages in the Monitor listbox, WorkFrame/2 sends a WM_DDE_EXECUTE "Goto" message for each selected error message. The "Goto" message tells the editor to scroll to a particular line in the source file. WorkFrame/2 also passes some information about the line. The format of the "goto" message is: ULONG cbData; /* Size of this structure + topic name + data */ USHORT fsStatus; /* ignore */ USHORT usFormat; /* ignore */ USHORT offszItemName; /* Offset to message topic name */ USHORT offabData; /* Offset to beginning of data area */ Topic name: CHAR message[]; /* Message topic name - "Goto" in this case */ Data area: ULONG errorline; /* Original source line in error */ ULONG erroroffset; /* Offset of error within error line */ ULONG resourceid; /* Resource ID of associated help panel in given help file */ ULONG magic_cookie; /* First line in Monitor window relating to error */ ULONG textlength; /* Length of errortext[], not including terminating NULL */ char errortext[]; /* ASCIIZ text of error message */ In response to this message, the editor should scroll to the given error line and place the cursor or mouse pointer at the given offset within the line. (The editor should allow for any tabs expansion since the given offset counts a tab as a single character). The editor is also passed the text of the message so that it can optionally be displayed in an information area. The resource ID (if it is not zero) can be used to display help for the error message: WinPostMsg (hwndHelp, /* Help window handle */ HM_DISPLAY_HELP, ulResID, /* MP1 - given resource ID */ HM_RESOURCE_ID); /* MP2 - MP1 contains resource ID */ 9. The editor should then send a WM_DDE_ACK message (as above) confirming acceptance of the command. 10. If the user asks to go to the next error, the editor can send a WM_DDE_DATA "SendGoto" message to ask the WorkFrame/2 program to send a WM_DDE_EXECUTE "Goto" message containing information about the next error. ULONG cbData; /* Size of stucture + topic name + data */ USHORT fsStatus; /* Ignore */ USHORT usFormat; /* Ignore */ USHORT offszItemName; /* Offset to message topic */ USHORT offabData; /* Offset to magiccookie data */ CHAR message[]; /* Message topic - "SendGoto" in this case */ ULONG magiccookie; /* The error message for which information is required */ The editor must send the "SendGoto" message with the magiccookie value of the error for which information is required. This value is given in the list of errors passed with the WM_DDE_EXECUTE "Initialize" message. See the pddeSendGoto() and pddeMakeRequest() functions of the WFEdit sample program for more information on how to allocate a giveable memory segment for the PDDESTRUCT structure, and how to initialize it for the "SendGoto" message. 11. If the user closes the Monitor window, WorkFrame/2 sends the editor a WM_DDE_TERMINATE message. The editor should then likewise send WorkFrame/2 a WM_DDE_TERMINATE message, agreeing to terminate the DDE session. WinDDEPostMsg (hwndWF, /* WorkFrame/2 window handle */ hwnd, /* Editor window handle */ WM_DDE_TERMINATE, /* Message ID */ NULL, /* DDE structure - not used */ TRUE); /* Options - not used */ If the user terminates the edit session while the DDE conversation is still active, the editor should send WorkFrame/2 a WM_DDE_TERMINATE message as part of its handling of the WM_CLOSE message. 12. This protocol is repeated for every new source file involved as the user double-clicks on errors in the Monitor window. As such, multiple editor sessions are invoked if the errors in the Monitor window involve more than one source file. ═══ 12.4. Action Support APIs ═══ This section describes functions that an application would use to query options settings, and obtain user-defined settings via a WorkFrame/2*-integrated graphical user-interface. The WorkFrame/2 program calls these APIs to: o Display and set options for the action - WkfQuery...Options o Retrieve the command line to execute for the action - WkfQuery...Target o Support make file creation - WkfQuery...Target - Wkf...Terminate o Provide error handling and context-sensitive help. - WkfQuery...ResourceID - WkfQuery...HelpFile - WkfQuery...ParseError - WkfQuery...QueryDDE These functions are defined in the WKFOPT.H header file. ═══ 12.4.1. WKF_REALLOC ═══ WKF_REALLOC Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WKF_REALLOC ═══ This WorkFrame/2*-provided callback function reallocates space for the buffer that has been passed to it. #define INCL_WKFOPT #include typedef PVOID APIENTRY WKF_REALLOC ( PVOID pvBuffer, /* Pointer to buffer to be reallocated */ ULONG ulNewSize /* New buffer length, in bytes */ ); typedef WKF_REALLOC *PWKF_REALLOC; ═══ Parameter - pvBuffer ═══ pvBuffer (PVOID) - input Address of the buffer to be reallocated. ═══ Parameter - ulNewSize ═══ ulNewSize (ULONG) - input New length, in bytes, of the buffer pointed to by pvBuffer . ═══ Return Values - WKF_REALLOC ═══ (PVOID) - return values WKF_REALLOC returns the following pointer values: NULL Error Other Pointer to the newly allocated buffer. ═══ Notes - WKF_REALLOC ═══ WKF_REALLOC is a WorkFrame/2-provided callback function that reallocates space for its argument buffer. PWKF_REALLOC is a pointer to the WKF_REALLOC function. This function passed as a parameter to the integrator-provided interfaces, WkfQuery...Options and WkfQuery...Target, to be used in case the initial allocation for an output buffer is too small. ═══ Example - WKF_REALLOC ═══ The integrator-provided interface WkfQuery...Options is called by the WorkFrame/2* program to query the user-specified options settings of a tool for a given project. A pointer to a buffer, pvOptions, containing the current options settings is passed to the interface (if no options settings exist yet, the buffer is uninitialized). During processing of the WkfQuery...Options API, new options settings are stored in the pvOptions buffer. If the buffer current allocation is insufficient to hold the new options settings, then the WKF_REALLOC API can be used to reallocate the buffer. The following pseudo-code shows how this function might be used within the WkfQuery...Options API (see WkfQuery...Options for its syntax): ULONG APIENTRY WkfQueryToolOptions ( ... PVOID pvOptions, PWKF_REALLOC pWkf_Realloc, ...) { MYOPTIONSSTRUCT NewOptions; ULONG ulNewBufSize; : GetNewOptions (&NewOptions); /* Get new options settings from user */ ulNewBufSize = sizeof (NewOptions); /* Get new size */ pvOptions = pWkf_Realloc (pvOptions, ulNewBufSize); /* Rellocate pvOptions buffer */ pvOptions->option1 = NewOptions->option1; /* Update pvOptions with new values */ pvOptions->option2 = NewOptions->option2; : return rc; } ═══ 12.4.2. WKF_PRT_STATUS ═══ WKF_PRT_STATUS Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WKF_PRT_STATUS ═══ This WorkFrame/2*-provided callback function prints the given status message on a status line, and then returns. #define INCL_WKFOPT #include typedef VOID APIENTRY WKF_PRT_STATUS ( PSZ pszStatusMsg /* String to print on message box */ ); typedef WKF_PRT_STATUS *PWKF_PRT_STATUS; ═══ Parameter - pszStatusMsg ═══ pszStatusMsg (PSZ) - input Address of the string to display for the status message. ═══ Return Values - WKF_PRT_STATUS ═══ (VOID) - return values WKF_PRT_STATUS has no return values. ═══ Notes - WKF_PRT_STATUS ═══ WKF_PRT_STATUS is a WorkFrame/2*-provided callback function that prints a status message and then returns. Use this function to provide on-going status to the user when processing takes significant time to complete. This function is not to be used for reporting errors since the message is displayed for a short period of time, and is overwritten by the next status message. An example of where these messages are displayed is in the WorkFrame/2 MakeMake program, while it is validating dependencies and creating the make file. This function accepts only a simple text string. No formatting is done. This function passed as a parameter to the integrator-provided WkfQuery...Target function. Any interface that is passed this callback function should check for a NULL value before attempting to use it. The WorkFrame/2 program passes a NULL value in its place when it determines that use of the callback function is not required. ═══ Example - WKF_PRT_STATUS ═══ WKF_PRT_STATUS is passed as a callback function to the integrator-provided WkfQuery...Target function. If processing within the WkfQuery...Target function takes a significant period of time, this function can be called periodically to provide ongoing status information to the user. The following pseudo-code shows how this function might be used within the WkfQuery...Target function: APIRET APIENTRY WkfQueryToolTarget ( ... PWKF_PRT_STATUS pWkf_PrtStatus, ... ); { : pWkf_PrtStatus ("Generating command line parameters ..."); < Generate command-line parameters > : pWkf_PrtStatus ("Generating list of target files ..."); < Discard unnecessary source files > < Generate target files list> : pWkf_PrtStatus ("Generating list of dependencies ..."); < Generate list of dependencies > : } ═══ 12.4.3. WkfQuery...Options ═══ WkfQuery...Options Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQuery...Options ═══ Write this integrator-provided function to optionally ?? display an options window, and return the user-selected options to be saved with the project file. #define INCL_WKFOPT #include typedef ULONG APIENTRY WKF_QUERY_OPTIONS ( HWND hwndWorkFrame, /* WF/2 frame handle or HWND_DESKTOP */ HMODULE hModHandle, /* Options dialog DLL module handle */ PSZ pszProject, /* Project file name */ PSZ pszTitle, /* Title to display on dialog */ PWKF_ACTION pwkfAction, /* Pointer to action information structure */ ULONG ulSetting, /* Load default or previous settings */ PULONG pulOptionsLength, /* Initial buffer size; contains actual size on exit */ PVOID pvOptions, /* Pointer to options buffer */ PWKF_REALLOC pWkf_Realloc, /* Pointer to buffer-reallocation function */ BOOL bFileScope /* TRUE if invoked for file-scoped actions, FALSE for project-scoped */ ); typedef WKF_QUERY_OPTIONS *PWKF_QUERY_OPTIONS; ═══ Parameter - hwndWorkFrame ═══ hwndWorkFrame (HWND) - input Window handle of the WorkFrame/2 frame window. Use HWND_DESKTOP if frame handle is not available. ═══ Parameter - hModHandle ═══ hModHandle (HMODULE) - input The handle of the dynamic link module containing this API. Use this parameter to access any resources bound to the DLL, such as string tables and dialog templates. ═══ Parameter - pszProject ═══ pszProject (PSZ) - input Address of the ASCIIZ project file name. ═══ Parameter - pszTitle ═══ pszTitle (PSZ) - input Address of the ASCIIZ project title. This is the title displayed with the project's Desktop icon. You can display this title on the options dialog to identify the project. ═══ Parameter - pwkfAction ═══ pwkfAction (PWKF_ACTION) - input Pointer to a PWKF_ACTION structure containing information about the action whose options to query. ═══ Parameter - ulSetting ═══ ulSetting (ULONG) - input Set this parameter to WKF_QO_SETTING_USE_OPTIONS (0x00) to initially display the options dialog with the settings as stored in the pvOptions buffer. Set this parameter to WKF_QO_SETTING_USE_DEFAULT (0X01) to display the default options settings. ═══ Parameter - pulOptionsLength ═══ pulOptionsLength (PULONG) - input/output Initial size, in bytes, of the buffer pointed to by pvOptions. On exit, this field points to the actual number of bytes used. ═══ Parameter - pvOptions ═══ pvOptions (PVOID) - input/output On entry, this pointer contains the address of an integrator-defined area containing the initial options settings. On exit, the area contains the user-specified settings. Note: This function should attempt to minimize the size of the area that contains the options settings since this area is written to a project file. ═══ Parameter - pWkf_Realloc ═══ pWkf_Realloc (PWKF_REALLOC) - input Pointer to the callback function for buffer reallocation. Call this function with WKF_REALLOC_OPTIONS as the first parameter if the pvOptions buffer gets too small to hold the new options settings information. ═══ Parameter - bFileScope ═══ bFileScope (BOOL) - input Specify TRUE for this parameter if the function is being invoked for a file-scoped action. Specify FALSE for project-scoped. ═══ Return Values - WkfQuery...Options ═══ (ULONG) - return values WkfQuery...Options should return the following values: 0 WKF_NOERROR No error occurred so save the options with the project file. This indicates that the user closed the options dialog by selecting the OK pushbutton. 2 WKF_CANCEL Do not save any changed options with the project file. This indicates that the user closed the options dialog by selecting the Cancel pushbutton. 8 WKF_ERROR An error occurred, that is, the DLL displayed an error message. ═══ Notes - WkfQuery...Options ═══ Write this function to optionally display an options dialog that enables the user to set options for the tool within a graphical user interface. Return the user-selected options in the integrator-defined buffer pointed to by pvOptions. If the current allocation for the pvOptions buffer is too small to hold the new options settings, call the pWkf_Realloc function with pvOptions and the new buffer size required. The return values from this function determine whether the user-selected options settings should be saved with the project file. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2* needs to call this function for an action of class COMPILE, it calls WKFQUERYCOMPILEOPTIONS(). Any spaces in the class name are converted to underscores. Related Information: o Guidelines for Designing an Options Interface ═══ Example - WkfQuery...Options ═══ The following pseudo-code illustrates how this interface could work: First, check whether the TOOLOPTIONS area pointed to by pvOptions contains the current options settings, then show the options dialog with the options set accordingly: struct TOOLOPTIONS CurrentOptions; ULONG *pulCurrentOptionsSize; if (ulSetting == WKF_QO_SETTING_USE_OPTIONS) /* pvOptions area is initialized */ { copy (CurrentOptions, pvOptions); /* Copy pvOptions area */ rc = GetNewOptions (hwndWorkFrame, /* Allow user to set options via */ hModHandle, /* a graphical user interface */ &CurrentOptions, /* Show options set to current settings */ pulOptionsLength, /* when user opens the options dialog */ pszTitle); } else if (ulSetting == WKF_QO_SETTING_USE_DEFAULT /* pvOptions area is uninitialized */ { GetDefaultSettings (&CurrentOptions); pulDefaultSize = sizeof (CurrentOptions); rc = GetNewOptions (hwndWorkFrame, hModHandle, &CurrentOptions, /* Show options set to default settings */ pulCurrentOptionsSize, pszTitle); } Now check to see how the user finished and return. if (rc == USER_CHANGED_OPTIONS) { pvOptions = pWkf_Realloc (pvOptions, *pulCurrentOptionsSize); copy (pvOptions, CurrentOptions); /* Update pvOptions area with current options */ return NO_ERROR; } else if (rc == USER_CANCELLED) { return WKF_CANCEL; } ═══ 12.4.4. WkfQuery...Target ═══ WkfQuery...Target Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQuery...Target ═══ Write this function to return information required by the WorkFrame/2* program to invoke the requested action on the selected project objects, or when building a make file. #define INCL_WKFOPT #include typedef APIRET APIENTRY WKF_QUERY_TARGET ( PVOID *ppvToolBuffer, /* Buffer created by actions support DLL */ HWND hwndWorkFrame, /* WF/2 frame handle or HWND_DESKTOP */ HMODULE hModHandle, /* Tool options DLL module handle */ PSZ pszProject, /* Project file name */ PSZ pszTitle, /* Project title */ PWKF_ACTION pwkfAction, /* Pointer to action information structure */ ULONG ulOptionsLength, /* Initial options buffer size; contains actual size on exit */ PVOID pvOptions, /* Pointer to options buffer */ ULONG ulCmdLineLength, /* Initial size of command line buffer */ PSZ pszCmdLine, /* Output command line buffer */ ULONG ulSearchPath, /* Initial size of search path buffer */ PSZ pszSearchPath, /* Buffer containing the search path */ LIST_OF_SOURCE *pstSourceObjects, /* List of selected source files */ LIST_OF_TARGET *pstTargetObjects, /* List of target file masks */ LIST_OF_DEPEND *pstDependObjects, /* List of dependencies */ PWKF_REALLOC pWkf_Realloc, /* Pointer to buffer-reallocation function */ PWKF_PRT_STATUS pWkf_PrtStatus, /* Pointer to print status function */ BOOL bFileScope /* TRUE if action is file-scoped; FALSE is project-scoped */ ); typedef WKF_QUERY_TARGET *PWKF_QUERY_TARGET; ═══ Parameter - *ppvToolBuffer ═══ *ppvToolBuffer (PVOID) - input Use this pvoid pointer to store tool-specific information so that it is available across subsequent calls to this function. For instance, information about imbedded dependency files can be saved here so that they would not have to be re-created on each call. Subsequent calls to this function for the same action class and name will then be passed this pointer value. After calling this function (e.g. during the creation of a make file), the WorkFrame/2* program checks the value of this pointer. If it is not NULL, WorkFrame/2 calls the integrator-provided function Wkf...Terminate to free any memory used. ═══ Parameter - hwndWorkFrame ═══ hwndWorkFrame (HWND) - input Window handle of the WorkFrame/2 frame window. Use HWND_DESKTOP if frame handle is not available. ═══ Parameter - hModHandle ═══ hModHandle (HMODULE) - input The handle of the dynamic link module containing this API. Use this parameter to access any resources bound to the DLL, such as string tables and dialog templates. ═══ Parameter - pszProject ═══ pszProject (PSZ) - input Address of the ASCIIZ project file name, which should not contain a path name or drive specification. ═══ Parameter - pszTitle ═══ pszTitle (PSZ) - input Address of the ASCIIZ project title. This is the title that is displayed with the project's Desktop icon. ═══ Parameter - pwkfAction ═══ pwkfAction (PWKF_ACTION) - input Pointer to a PWKF_ACTION structure containing information about the action to query. ═══ Parameter - ulOptionsLength ═══ ulOptionsLength (ULONG) - input Size, in bytes, of the buffer pointed to by pvOptions. ═══ Parameter - pvOptions ═══ pvOptions (PVOID) - input The address of an integrator-defined structure containing the options settings for the action given in the pwkfAction structure, and the project named in pszProject. ═══ Parameter - ulCmdLineLength ═══ ulCmdLineLength (ULONG) - input Initial size, in bytes, of the pszCmdLine buffer. ═══ Parameter - pszCmdLine ═══ pszCmdLine (PSZ) - input/output On exit, this pointer should contain the address of a buffer containing the command-line parameters to be used by this action, given the list of valid source-files selected by the user (*pstSourceObjects) and options set by the user (pvOptions). This buffer may contain *wkft. substitution variables where applicable. This buffer may also contain the special character WKF_CMDLINE_INLINEFILE as described below. It provides extra flexibility where necessary, but should be avoided if possible. WKF_CMDLINE_INLINEFILE WKF_CMDLINE_INLINEFILE must always be included in the command string in pairs. The characters are removed and replaced by a temporary file name, and all the characters in between placed in this file, verbatim (no processing will be done on these characters). The temporary file is deleted after the command has completed execution. This can be used to execute a command via a response file, which should be used if the output length exceeds 1024 characters (which is the most cmd.exe will accept, and thus the longest that can be placed in a makefile). ═══ Substitution Variables ═══ Substitution variables are place holders for items like file names and option strings. They are used when one wants to define a string without being too specific. For example, you could write the command string icc /Ti /C c:\dog\terrier.cpp as icc /Ti /C %f where %f is the selected file c:\dog\terrier.cpp. The substitution variables that you can use with the WorkFrame/2 product are: %a...%z Replaced by the names of all the selected files, separated by a space. If the ellipses between the 'a' and the '%' is replaced by a character, then the names are separated by the specified character. For example, if the selected files are d:\cat.obj, d:\dog.obj and d:\bird.obj , the substitution variable %a+%z will produce the string d:\cat.obj+d:\dog.obj+d:\bird.obj . The only substitution variables allowed within the %a...%z substitution variables are %% and %d. %d Is replaced with the project's working directory. %e Is replaced by the extension (including the period) of the first selected file. %f Is replaced with the fully-qualified name of the first selected file. Specifying %f is the same as specifying %q%n%e. %m Is replaced by the make file name specified for the project in its Settings notebook. %n Is replaced by the file name (without an extension and path) of the first selected file. %o Is replaced by the target file name specified for the project in its Settings notebook. %p Is replaced by the fully-qualified project file name. %q Is replaced by the path of the first selected file. %r Is replaced by the run options set for the project target file in the project's Settings notebook. %TOPIC% Is replaced by the contents of the Help Topic field in the action's Settings notebook. This field specified the help topic to be displayed when the user requests for help on the action. %% Is replaced by the % symbol. Example If the first selected file is d:\dogs\hounds\beagle.h , then: %e is .h %f is d:\dogs\hounds\beagle.h %n is beagle %q is d:\dogs\hounds\ Note: If the file name includes spaces, such as toy terrier.h , then the file name part of the substituted string will have quotation marks surrounding it. For example, %f would be replace by "toy terrier.h" . ═══ Parameter - ulSearchPath ═══ ulSearchPath (ULONG) - input Initial size, in bytes, of the pszSearchPath buffer. ═══ Parameter - pszSearchPath ═══ pszSearchPath (PVOID) - input/output On entry, this buffer contains a list of the project's source directories, each delimited by a WKF_LIST_DELIM character. On exit, this buffer should contain the list of paths in which to search for the required source files and dependency files. The paths should be separated by a semi-colon. If necessary, this buffer may be reallocated using the pWkf_Realloc callback function. ═══ Parameter - *pstSourceObjects ═══ *pstSourceObjects (LIST_OF_SOURCE) - input/output On entry, this buffer contains a list of input source files selected by the user. On exit, each entry in the list is marked to indicate whether or not the file is used by the action, or whether it is to be used and then discarded. This field contains a list of SOURCE_ENTRY structures, each containing the filename and use-code for each source file. Write this function to update the SOURCE_ENTRY structure's fUsed member to contain one of the following values for each source file on exit: 0 WKF_QT_FILE_NOTUSED File is not processed by selected action. 1 WKF_QT_FILE_USED File is processed and required by action. 2 WKF_QT_FILE_DISCARD File is processed and to be discarded. ═══ Parameter - *pstTargetObjects ═══ *pstTargetObjects (LIST_OF_TARGET) - input/output This parameter may be NULL on entry. If it is NULL, do nothing with this pointer. If it is not NULL, then on exit, this pointer should contain the list of output files that will be generated upon successful completion of the specified action. Note: This list should only include files generated by a single invocation of the action. For example, a LINK action may create .EXE and .MAP files. ═══ Parameter - *pstDependObjects ═══ *pstDependObjects (LIST_OF_DEPEND) - input/output This parameter may be NULL on entry. If it is NULL, do nothing with this list. If it is not NULL, then on exit, this pointer should contain the list of dependencies (that is, the files on which the action of building the files in the pstTargetObjects list depends on), excluding those marked in the pstSourceObjects list. This list should be complete -- the files returned in this list will not be parsed further by the WorkFrame/2* program for nested includes. Note: You can use the *ppvToolBuffer field to save any information needed to eliminate the need to reparse files. ═══ Parameter - pWkf_Realloc ═══ pWkf_Realloc (PWKF_REALLOC) - input Pointer to the callback function for buffer reallocation. If one of the output buffers is too small, call this function with the field to be adjusted, and the new buffer size required, in bytes. The following output buffers can be reallocated using this callback function: o pstTargetObjects o pstDependObjects o pszCmdLine o pszSearchPath. Note: For the pstTargetObjects and pstDependObjects fields, you do not need to account for the two ULONG fields in their structures. The bytes required should be for the buffer itself only. ═══ Parameter - pWkf_PrtStatus ═══ pWkf_PrtStatus (PWKF_PRT_STATUS) - input Pointer to the WorkFrame/2*-provided callback function for printing a status message. If processing takes a significant period of time, call this function periodically to provide ongoing status information to the user. If processing time is very small, use of this function is not necessary. Do not use it to report errors as the message is only displayed temporarily in a status area on the screen. This pointer can be NULL on entry. This means that the callback function is not available (that is, the WorkFrame/2 program will not display any status messages for the current invocation of this function). ═══ Parameter - bFileScope ═══ bFileScope (BOOL) - input Specify TRUE for this parameter if the function is being invoked for a file-scoped action; FALSE for project-scoped. ═══ Return Values - WkfQuery...Target ═══ (APIENTRY) - return values WkfQuery...Target should return the following values: 0 No error. !0 An error occurred (options DLL displayed an error message). Processing aborted. ═══ Notes - WkfQuery...Target ═══ Given a list of valid source files selected by the user, and options set by the user, write this integrator-provided function to return the following: 1. The command-line parameters to be used by this action (in the pszCmdLine field) 2. From the list of input files, mark those which will apply to this action, and those which should be discarded (in the pstSourceObjects field). If this field is NULL on entry, do nothing with it. Any unmarked files will result in this function being called again for the same action, with the unmarked files listed in the pstSourceObjects field. You can use this mechanism to control the way an action is invoked on a set of files. For example, if the action was a compile, you could parse the source files to determine if templates are being used, and then mark only the files that use templates to apply to the action, and then include the correct options to compile the template files in the command-line parameters returned by this function. Any unmarked files will be passed to this function on a subsequent call for the same action, so you can continue processing for these files. 3. If the target objects list pointer is not NULL, then return a list of output files to be generated by this action (in the pstTargetObjects field). Note: This list should only include files created by a single invocation of the action. For example, a LINK action may create .EXE and .MAP files. 4. If the dependency objects list pointer is not NULL, then return the list of files on which the action of building the TARGET file depends (excluding those marked in the list of input files) in the pstDependObjects field. This list should be complete -- files returned will not be parsed further by WorkFrame/2* for nested includes. This function may be called as many times as necessary to complete processing, for example, during make file creation. Make file creation usually requires calling this function for a number of different actions. This function is called at least once for every action involved in the make. Store any error or warning messages you wish to display to the user after all processing has been completed in the *ppvToolBuffer buffer. You can display these error messages as part of the processing of the Wkf...Terminate function when the WorkFrame/2 program calls it with this buffer. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, it calls WKFQUERYCOMPILETARGET(). Any spaces in the class name are converted to underscores. ═══ Example - WkfQuery...Target ═══ @@@@@@@@@@ ═══ 12.4.5. Wkf...Terminate ═══ Wkf...Terminate Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - Wkf...Terminate ═══ Write this function to free any memory allocated by *ppvToolBuffer (parameter to the WkfQuery...Target API), and to display any saved error or warning messages. #define INCL_WKFOPT #include typedef APIRET APIENTRY WKF_TERMINATE ( PVOID pvToolBuffer, /* Buffer created by tool options DLL */ BOOL fDisplayMessages, /* Indicates whether messages should be displayed */ HWND hwndWorkFrame, /* WF/2 frame handle or HWND_DESKTOP */ HMODULE hModHandle, /* Tool options DLL module handle */ PSZ pszTitle, /* Project title */ PWKF_ACTION pwkfAction /* Pointer to action information structure */ ); typedef WKF_TERMINATE *PWKF_TERMINATE; ═══ Parameter - pvToolBuffer ═══ pvToolBuffer (PVOID) - input Use this pointer to free all memory allocated to it points to. Storage for this buffer is allocated and initialized in the WkfQuery...Target function. After the every call to the WkfQuery...Target function, the WorkFrame/2* program checks the returned value of the *ppvToolBuffer output parameter. If it is not NULL, the WorkFrame/2 program saves the pointer value in its own allocated storage and then calls this function with the saved pointer value in this parameter. ═══ Parameter - fDisplayMessages ═══ fDisplayMessages (BOOL) - input The WorkFrame/2* program sets this parameter to indicate whether or not any saved error or warning messages should be displayed in a message box or similar mechanism supplied by this function. The WorkFrame/2 program allows the WkfQuery...Target function to save error or warning messages in its *ppvToolBuffer You can then use this function to display saved warning messages that the user does not need to see until processing has finished. Display messages only if this parameter is set to TRUE. ═══ Parameter - hwndWorkFrame ═══ hwndWorkFrame (HWND) - input Window handle of the WorkFrame/2 frame window. Use HWND_DESKTOP if frame handle is not available. ═══ Parameter - hModHandle ═══ hModHandle (HMODULE) - input The handle of the dynamic link module containing this API. Use this parameter to access any resources bound to the DLL, such as string tables and dialog templates. ═══ Parameter - pszTitle ═══ pszTitle (PSZ) - input Address of the ASCIIZ project title. This is the title shown with project's desktop icon. ═══ Parameter - pwkfAction ═══ pwkfAction (PWKF_ACTION) - input Pointer to a PWKF_ACTION structure containing information about the action to query. ═══ Return Values - Wkf...Terminate ═══ (APIRET) - return values Wkf...Terminate should return the following values: 0 No error. !0 An error occurred (an error message was displayed). Processing aborted. ═══ Notes - Wkf...Terminate ═══ This function is called when the WorkFrame/2* program is finished with the Options DLL and is about to unload it. After the WorkFrame/2* program has called the WkfQuery...Target function one or more times, it checks the saved returned value of the *ppvToolBuffer output parameter. If it is not NULL, the WorkFrame/2 program saves the pointer value in its own allocated memory, and this function will be called with the saved pointer value as the first parameter. This function is expected to free any allocated memory that it has allocated for the *ppvToolBuffer buffer and display any saved error or warning messages. This function may also perform any necessary final processing tasks. The WkfQuery...Target may have stored one or more error or warning messages in the *ppvToolBuffer area for display when all processing has completed (for example, after the creation of a make file). Error messages should only be displayed if the fDisplayMessages flag is set to TRUE. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, calls WKFCOMPILETERMINATE(). Any spaces in the class name are converted to underscores. ═══ Example - Wkf...Terminate ═══ @@@@@@@@@@ ═══ 12.4.6. Wkf...ParseError ═══ Wkf...ParseError Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - Wkf...ParseError ═══ Write this function to parse one or more selected output lines from an invocation of the integrated tool in the Monitor window. This function is expected to return information such as the filename, line number, and column number, for every valid error message within a range of output lines. #define INCL_WKFOPT #include typedef ULONG APIENTRY WKF_PARSEERROR ( HWND hwndErrorBox, /* Window handle of error message listbox in Monitor window */ PSZ pszProject, /* Project file name */ PUSHORT pusStartLine, /* Index of first line in range of parsed lines in hwndErrorBox listbox */ PUSHORT pusEndLine, /* Index of last line in range of parsed lines */ HWND hwndFilenames, /* Window handle of listbox to insert filenames into */ PUSHORT pusCurrentFile, /* Index into hwndFilename listbox of file where selected error occurred */ PVOID pvOptions, /* Pointer to area containing tool options */ PULONG pulSetting /* Validity of options, indicates if initialized */ ); typedef WKF_PARSEERROR *PWKF_PARSEERROR; ═══ Parameter - hwndErrorBox ═══ hwndErrorBox (HWND) - input The handle of the listbox in the Monitor window that contains output from an invocation of the integrated tool. Use this handle to obtain the line selected by the user (send a LM_QUERYSELECTION message to this listbox), and to read output text (send a LM_QUERYITEMTEXT message). This function is also expected to store additional information about each error within the range of parsed lines specified by the pusStartLine and pusEndLine fields. This information is stored in the item handle of each valid error line in this listbox. To set the item handle for a valid error line, declare and initialize a WKF_TAGPARAM variable, and then send a LM_SETITEMHANDLE message to the hwndError listbox with a pointer to the initialized WKF_TAGPARAM structure in MP2, and the index of the associated item in MP1. ═══ Parameter - pszProject ═══ pszProject (PSZ) - input The name of the project file of the project for which the action was invoked. ═══ Parameter - pusStartLine ═══ pusStartLine (PUSHORT) - output Update this parameter to contain the index of the first line in the range of lines within the hwndErrorBox listbox that have been parsed by this function. ═══ Parameter - pusEndLine ═══ pusEndLine (PUSHORT) - output Update this parameter to contain the index of the last line in the range of lines within the hwndErrorBox listbox that have been parsed by this function. ═══ Parameter - hwndFilenames ═══ hwndFilenames (HWND) - input Handle of the hidden listbox into which this function must insert the name of each source file that contains the errors within the range specified by the pusStartLine and pusEndLine fields. The contents of this listbox persist between calls to the this API. If a line in the parsed range of lines contains a valid error message, this function should use this listbox handle to insert the name of the source file in which the error occurred. The index of the inserted filename should be encoded into a WKF_TAGPARAM structure which is stored in the item handle of the associated hwndErrorBox message line. Note: This listbox may already contain file names in it from a previous call to this function. Before adding a file name to this listbox, this function should first ensure that the file name has not already been inserted into the listbox by sending the listbox a LM_SEARCHSTRING message. If the file name is already present in the listbox, just use the existing index for encoding into the WKF_TAGPARAM structure ═══ Parameter - pusCurrentFile ═══ pusCurrentFile (PUSHORT) - output Set this parameter to the index of the filename in the hwndFilenames listbox that contains the error in the line selected by the user. The WorkFrame/2* program will invoke the editor for this file. ═══ Parameter - pvOptions ═══ pvOptions (PVOID) - input The address of an integrator-defined buffer containing the existing options settings for the invoked action. Note: This buffer is unitialized if the pulSetting flag is set to WKF_SETTING_USE_DEFAULT. ═══ Parameter - pulSetting ═══ pulSetting (PULONG) - input Flag to indicate whether options settings exist for the invoked action. It can contain one of the following values: 0x00 WKF_SETTING_USE_OPTIONS Options settings exist for the invoked action; the pvOptions buffer is initialized with the current settings. 0x01 WKF_SETTING_USE_DEFAULT Options have not previously existed for the invoked action. The pvOptions buffer is uninitialized. ═══ Return Values - Wkf...ParseError ═══ (ULONG) - return values Wkf...ParseError should return the following values: 0 WKF_PARSEERROR_SUCCESS No error. 1 WKF_PARSEERROR_ERROR An error occurred (options DLL displayed an error message). Processing aborted. 2 WKF_PARSEERROR_INVALID Line invalid or not recognized ═══ Notes - Wkf...ParseError ═══ A tool, such as a compiler, that writes its output to one of the standard output handles ( stdout or stderr ) can have its output redirected back to the WorkFrame/2* program so that the output is displayed in a listbox in the Monitor window. When an action runs in the Monitor window, the user can double-click on a line of output to invoke the default editor for a valid error message. Wkf...ParseError is invoked by the WorkFrame/2 program each time the user double-clicks on a line of output in the Monitor window. Similar processing occurs when the user begins to drag a selected error message from the Monitor window to the editor. This interface is expected to parse the selected line, and usually, a range of lines above and below it, to return information about each valid error line, such as the file name, line number, and offset where the error occurred. You can choose to parse only the selected line, a range of lines, or all the lines in the monitor window for errors within a single invocation of this function. Return the range of parsed lines to the WorkFrame/2 program by updating the pusStartLine and pusEndLine. fields. For example, if this function parses the entire listbox, pusStartLine should contain zero and pusEndLine should contain the index of the last item in the hwndErrorBox listbox. This function is invoked each time the user selects a line that has not been parsed. Choosing how many lines to parse within one invocation of this function is a design choice that the tool integrator must make. Parsing only one line at a time is the simplest to code, however, the editor will only have information about one error at a time, and the interface will have to be called each time the user selects another error line. Parsing all the lines at once gives the editor all the information up front, however, if the number of errors is large, there may be a noticeable delay when the editor is first started. The name of each file that contains an error within the parsed range of lines should be inserted into the hwndFilenames listbox. For each valid error message line within the parsed range of lines in the hwndErrorBox listbox, information about the error should be encoded and placed into a WKF_TAGPARAM structure. The WKF_TAGPARAM structure encodes the following information: the index into the hwndFilenames listbox that points to the name of the file containing the associated error, the line number where the error occurs within the file, and the offset of the error within the line. A pointer to the WKF_TAGPARAM structure should be placed in the item handle of the associated hwndErrorBox item. In the pusCurrentFile field, return the index into the hwndFilenames listbox of the first file that contains errors within the selected line. The editor will be invoked for this file initially. If the EPM editor is invoked for the file, each line that contains an error is highlighted. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, it calls WKFCOMPILEPARSEERROR(). Any spaces in the class name are converted to underscores. Related information: o DDE Interaction with Editors ═══ Example - Wkf...ParseError ═══ The following pseudo-code illustrates how processing for this function might proceed. First, obtain the line selected by the user: if ((sIndex = SHORT1FROMMR( WinSendMsg(hwndErrorBox, LM_QUERYSELECTION, (MPARAM)NULL, (MPARAM)NULL))) ==LIT_NONE) /* No line was selected */ return WKFRC_PARSEERROR_ERROR; Next, get the text of the line and determine whether it contains a valid error message: PSZ textbuffer; /* Buffer into which the item text is to be copied */ WinSendMsg (hwndErrorBox, LM_QUERYITEMTEXT, MPFROM2SHORT (sIndex, sizeof(textbuffer)), MPFROMP (textbuffer)); If ((rc = Parsetheline (textbuffer, ...)) == INVALID_ERROR) return WKFRC_PARSEERROR_INVALID; If the line contains a valid error message, the function must specify the range of lines it intends to parse. (In this example, we will parse only the selected line. However, we can choose to parse a range of lines, in which case further processing will apply to each line within the specified range of lines that contains a valid error message.) pusStartline = pusEndline = sIndex; Next, this function must insert the name of the file in which the error occurred in the hwndFilenames listbox. First, however, ensure that an index was not previously assigned for this file: insertIndex = SHORT1FROMMR (WinSendMsg(hwndFilenames, LM_SEARCHSTRING, MPFROM2SHORT (LSS_CASESENSITIVE, LIT_FIRST), MPFROMP (pszSourceFile))); if (insertIndex == LIT_ERROR) /* Index already assigned, no further processing required */ return WKF_PARSEERROR_ERROR; if (insertIndex == LIT_NONE) /* No index previously assigned, so insert file name */ insertIndex = SHORT1FROMMR (WinSendMsg(hwndFilenames, LM_INSERTITEM, MPFROMSHORT (LIT_END), (MPARAM) pszSourceFile)); If the current line being processed is the line that the user selected (in this case, it is), then the index into the hwndFilename listbox that corresponds to the name of the file where the error occurred should be returned in the pusCurrentFile field. Note that this only applies to the line that was actually selected by the user. pusCurrentFile = insertIndex; Lastly, information about the error is encoded and placed in the item handle of the associated hwndErrorBox item. WKF_TAGPARAM mpParam; mpParam.sub.errorLine = lineNumber; /* Line where error occurred */ mpParam.sub.offset = 0; /* Offset is optional */ mpParam.sub.fileNumber = sIndex; /* hwndFilenames listbox index to the name of the file where the error occurred */ WinSendMsg (hwndErrorBox, LM_SETITEMHANDLE, MPFROMSHORT (sIndex), (MPARAM)(ULONG)(mpParam.tagParam)); ═══ 12.4.7. WkfQuery...HelpFile ═══ WkfQuery...HelpFile Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQuery...HelpFile ═══ Write this function to return the name of the help file that provides help for the integrated tool's error messages. #define INCL_WKFOPT #include typedef ULONG APIENTRY WKF_QUERYHELPFILE2 ( HWND hwndErrorBox, /* Window handle of error message listbox in Monitor window */ PSZ pszProject, /* Project file name */ PSZ pszHelpFile /* Pointer to name of help file */ ); typedef WKF_QUERYHELPFILE2 *PWKF_QUERYHELPFILE2; ═══ Parameter - hwndErrorBox ═══ hwndErrorBox (HWND) - input The handle of the listbox in the Monitor window that contains output from an invocation of the integrated tool. If all the error messages for the tool are contained in a single help file, you may not need to use this handle. However, you may want to return a different help file depending on the error message if more than one help file exists. ═══ Parameter - pszProject ═══ pszProject (PSZ) - input The name of the project file of the project for which the action was invoked. ═══ Parameter - pszHelpFile ═══ pszHelpFile (PSZ) - output Update this field to contain the name of the IPF help (.HLP) file containing the help for the tool's error messages. ═══ Return Values - WkfQuery...HelpFile ═══ (ULONG) - return values WkfQuery...HelpFile should return the following values: FALSE No error message help file support exists for the tool. TRUE Help file returned in pszHelpFile field. ═══ Notes - WkfQuery...HelpFile ═══ When the user clicks on an error message from an invocation of the integrated tool in the Monitor window, the WorkFrame/2* program calls the Wkf...ParseError API to obtain information about the error. It then calls this function to obtain the name of the IPF help (.HLP) file that provides help for the integrated tool's error messages, if one exists. The WorkFrame/2 program then starts an edit session to display the source file in which the selected error occurs, and begins a dynamic data exchange (DDE) with the editor. If the editor invoked is the EPM editor, the user can request help for a selected error by selecting the Describe error menu item from the Compile pull-down. When the user requests help for an error, the WorkFrame/2 program calls the WkfQuery...ResourceID API to obtain the resource number of the appropriate help panel to display. If help for error messages is supported, write this function to set the pszHelpFile field to the name of the IPF help (.HLP) file that contains the help, and return TRUE. If help is not supported, return FALSE. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, it calls WKFQUERYCOMPILEHELPFILE(). Any spaces in the class name are converted to underscores. ═══ Example - WkfQuery...HelpFile ═══ The following pseudo-code illustrates how processing for this function might proceed. If help is supported for the tool's error messages, return the name of the help file in the pszHelpFile field: strcpy (pszHelpFile, "TOOLHELP.HLP"); return TRUE; If no help for error messages exists: return FALSE; ═══ 12.4.8. WkfQuery...ResourceID ═══ WkfQuery...ResourceID Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQuery...ResourceID ═══ Given the text of a particular error message, write this function to return the resource number (or res id) of the corresponding panel in the help file identified by the WkfQuery...HelpFile API. #define INCL_WKFOPT #include typedef ULONG APIENTRY WKF_QUERYRESOURCEID2 ( HWND hwndErrorBox, /* Window handle of error message listbox in Monitor window */ PSZ pszProject, /* Project file name */ PSZ pszErrorLine /* Pointer to the selected error message string */ ); typedef WKF_QUERYRESOURCEID2 *PWKF_QUERYRESOURCEID2; ═══ Parameter - hwndErrorBox ═══ hwndErrorBox (HWND) - input The handle of the listbox in the Monitor window that contains output from an invocation of the integrated tool. The string pointed to by the pszErrorLine field contains the text of a selected error message in this listbox. ═══ Parameter - pszProject ═══ pszProject (PSZ) - input The name of the project file of the project for which the action was invoked. ═══ Parameter - pszErrorLine ═══ pszErrorLine (PSZ) - input The text of the selected error message. The contents of this field correspond to a single line of output in the hwndErrorBox listbox. ═══ Return Values - WkfQuery...ResourceID ═══ (ULONG) - return values WkfQuery...ResourceID should return the following values: 0 There is no corresponding help panel for the given error message >20000 Help file resource ID corresponding to the given error message ═══ Notes - WkfQuery...ResourceID ═══ When the user clicks on an error message from an invocation of the integrated tool in the Monitor window, the WorkFrame/2* program calls the Wkf...ParseError API to obtain information about the error. It then calls this function to obtain the name of the IPF help (.HLP) file that provides help for the integrated tool's error messages, if one exists. The WorkFrame/2 program then starts an edit session to display the source file in which the selected error occurs, and begins a dynamic data exchange (DDE) with the editor. If the editor invoked is the EPM editor, the user can request help for a selected error by selecting the Describe error menu item from the Compile pull-down. When the user requests help for an error, the WorkFrame/2 program calls the WkfQuery...ResourceID API to obtain the resource number of the appropriate help panel to display. If help for the error message exists, write this function to return the resource number of the help panel that contains help for the error message given in the pszErrorLine field. Return a resource ID greater than 20000 since values from 0 through 20000 are reserved for use by the editor. If there is no help for the error message, return 0. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, it calls WKFQUERYCOMPILERESOURCEID(). Any spaces in the class name are converted to underscores. ═══ Example - WkfQuery...ResourceID ═══ The following pseudo-code illustrates how processing for this function might proceed. If help is supported for the error message passed in the pszErrorLine field, return the resource number of the corresponding panel in the help file returned by the WkfQuery...HelpFile API. For example, if the error message text is: PMLINES.C(176) XXX4023W Error: syntax error The task of the GetErrorMessageCode() function is to get the identifier XXX4023 from the message line. ErrorMessageCode = GetErrorMessageCode(pszErrorLine); Next, look up the corresponding resource number for the error message code and return it: ResourceID = LookupResourceID (ErrorMessageCode); if ResourceID > 20000 then return ResourceID else return 0; If no help exists for the passed error message: return 0; ═══ 12.4.9. WkfQuery...DDE ═══ WkfQuery...DDE Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQuery...DDE ═══ Write this function to inform the WorkFrame/2* program whether or not a Dynamic Data Exchange (DDE) session can be started with the integrated tool. Currently, this interface is supported only for EDIT class tools. #define INCL_WKFOPT #include typedef BOOL APIENTRY WKF_QUERYDDE ( PVOID pvOptions /* Pointer to area containing the tool options */ ); typedef WKF_QUERYDDE *PWKF_QUERYDDE; ═══ Parameter - pvOptions ═══ pvOptions (PVOID) - input The address of an integrator-defined structure containing the options settings for the tool. ═══ Return Values - WkfQuery...DDE ═══ (BOOL) - return values WkfQuery...DDE should return the following values: TRUE A DDE session can be started with the integrated tool. FALSE DDE is not supported. ═══ Notes - WkfQuery...DDE ═══ This interface is invoked to determine whether or not a Dynamic Data Exchange (DDE) session can be started with the integrated tool. Currently, this interface is supported only for EDIT class tools. The WorkFrame/2* Monitor window starts a DDE session with a specified DDE-enabled editor when the user double-clicks on an error message in the Monitor window to edit the file in which the error occurred. Define this function so that the actual entry point is named as above, with the ellipses replaced by the tool's class name, and the entire name upper-cased. For example, when WorkFrame/2 needs to call this function for an action of class COMPILE, it calls WKFQUERYCOMPILEDDE(). Any spaces in the class name are converted to underscores. ═══ Example - WkfQuery...DDE ═══ The following pseudo-code illustrates how processing for this function might proceed. @@@@@ ═══ 13. Project Access Method ═══ This section provides instructions on how to create a PAM, and describes, in detail, the function entrypoints you need to provide. ═══ 13.1. How to Create a PAM ═══ A PAM is an integrator-provided DLL containing all the required entrypoints for the functions described in this section. Follow these instructions to create a PAM DLL: 1. Include all the required entrypoints (described here and in the WKFPAM.H header file) in a single DLL. Include optional entry points as needed. 2. Since only one PAM can be specified for a base project, any new PAM you write must provide at least the same OS/2* support as the Basic PAM (DDE3BPAM.DLL) shipped with the WorkFrame/2* program. You can do this by providing the code to do this yourself or simply by chaining to the Basic PAM DLL. To chain to the Basic PAM DLL, call the corresponding Basic PAM entrypoints as part of the processing of your own PAM's entrypoints. See the PeterPAM sample program for a demonstration on how to chain PAMs. 3. Provide only 32-bit interfaces that use the system linkage convention. 4. Use address parameters that contain flat memory addresses. 5. Handle errors by returning the appropriate OS/2-defined return code from a call to an OS/2 API in your functions. If an error cannot be mapped to an equivalent OS/2 return code, return WKFPAM_ERROR, as defined in the WKFPAM.H header file. In this case, you will need to return an error message to be displayed to the user, as described in the next item. 6. Most PAM API's have two parameters that provide convenient error message handling capabilities: cbMessage and pszMessage . On entry, cbMessage contains the number of bytes allocated for the message buffer pszMessage . Before exiting, store a NULL-delimited string containing the message you want displayed to the user in the pszMessage buffer. The WorkFrame/2 program will display the message in an error message box. If an OS/2 error occurred, it will append the pszMessage string to the OS/2 message. 7. The first argument to nearly all the PAM functions is a PAM handle (HAM) that is associated with a specific project. This unique handle is generated by the PAM-provided WkfQueryHAM function. This HAM value is typically a pointer to a PAM-defined structure that holds any PAM-specific information that needs to be kept between PAM function calls for the associated project. For example, the session ID for an action being started for a project by WkfRun should be stored in the HAM so that WkfStop can identify the session to be halted. ═══ 13.2. Project Access Method APIs ═══ This section descibes: 1. WorkFrame/2*-supplied macros for use in writing a Project Access Method (PAM) - WKFPAM_NEXTPART - WKF_ADDFILES - WKF_ADDMONITOR 2. Functions that must be supplied by the PAM writer, such as: o A query method for retrieving the list of project parts for a project o A run method for invoking actions on the target system o Methods for direct manipulation of files The required PAM interfaces can be categorized into 4 general groups: o Setup - WkfQueryHAM - WkfQueryPathInfo - WkfQueryTitle - WkfCreatePath - WkfDefaultName - WkfSettings o Parts list querying - WkfQueryFiles o Direct manipulation - WkfQueryCopy - WkfCopyFile - WkfDelete o Action support - WkfQueryRunnable - WkfRun - WkfStop The function prototypes and the macro definitions for Project Access Method APIs are in the WKFPAM.H C header file. ═══ 13.2.1. WKFPAM_NEXTPART ═══ WKFPAM_NEXTPART Select an item: Macro Definition Notes Examples ═══ Definition - WKFPAM_NEXTPART ═══ Use this macro to move from one project part to the next. #define WKFPAM_NEXTPART(p) (PWKFPAM_PART)((PCHAR)p+p->cb) ═══ Parameter - p ═══ p (WKFPAM_PART) A single element in the list of project parts passed back to the WKF_ADDFILES callback function. ═══ Notes - WKFPAM_NEXTPART ═══ WKFPAM_NEXTPART is a WorkFrame/2-provided macro that returns the next part in a list of project parts. The WKF_ADDFILES callback function expects a list of project parts. This macro can be used to traverse the list. ═══ Example - WKFPAM_NEXTPART ═══ The following pseudo-code illustrates the use of this macro: @@@@@ ═══ 13.2.2. WKF_ADDFILES ═══ WKF_ADDFILES Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WKF_ADDFILES ═══ This WorkFrame/2*-provided callback function adds a file to the files container view of a base project. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_ADDFILES ( PVOID pvPrivateData, /* Pointer to caller-specific data */ PSZ pszContainer, /* Path name of directory to store files into */ ULONG ulCount, /* Number of WKFPAM_PART entries pointed to by pwppData */ PWKFPAM_PART pwppData /* Start of data block containing WKFPAM_PART list */ ); typedef WKF_ADDFILES *PWKF_ADDFILES; ═══ Parameter - pvPrivateData ═══ pvPrivateData (PVOID) - input A pointer to WorkFrame/2*-private information used in the processing of this callback function. This pointer is passed by the WorkFrame/2 program to the PAM-provided API, WkfQueryFiles, which uses this callback function. The WkfQueryFiles should pass this pointer to the callback function when calling it. The information addressed by this pointer is private to WorkFrame/2 processing and is not to be used by PAM-provided functions. ═══ Parameter - pszContainer ═══ pszContainer (PSZ) - input Path name of the directory in which to store the project parts in the list pointed to by the pwppData field. ═══ Parameter - ulCount ═══ ulCount (ULONG) - input The number of WKFPAM_PART entries in the list pointed to by the pwppData field. ═══ Parameter - pwppData ═══ pwppData (PWKFPAM_PART) - input Address of the start of the data block containing the list of WKFPAM_PART structures. Each WKFPAM_PART structure describes a project part in the list of parts to add to a project. The PAM-provider must ensure that the WKFPAM_PART entries are stored contiguously in memory by allocating a large chunk of memory at once, and then sub-allocating memory for each WKFPAM_PART entry as needed. ═══ Return Values - WKF_ADDFILES ═══ (APIRET) - return values WKF_ADDFILES returns the following values: 0 NOERROR Items were added successfully. Other OS/2*-defined return code. ═══ Notes - WKF_ADDFILES ═══ This callback function is passed to the WkfQueryFiles API to add one or more parts (e.g. files) to the caller's base project parts list. The list of project parts is addressed by the pwppData field, which points to a list of WKFPAM_PART structures, each structure representing a single project part entry in the list. Project parts can only be added to one directory or container (specified by the pszContainer field) for a single invocation of this function. ═══ Example - WKF_ADDFILES ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.3. WKF_ADDMONITOR ═══ WKF_ADDMONITOR Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WKF_ADDMONITOR ═══ This WorkFrame/2*-provided callback function adds output lines to the Monitor listbox. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_ADDMONITOR ( PVOID pvPrivateData, /* Pointer to caller-specific data */ PSZ pszLine /* String to be displayed */ ); typedef WKF_ADDMONITOR *PWKF_ADDMONITOR; ═══ Parameter - pvPrivateData ═══ pvPrivateData (PVOID) - input A pointer to WorkFrame/2* private information used in the processing of this callback function. This pointer is passed by the WorkFrame/2 program to the PAM-provided API, WkfRun, which uses this callback function. The caller should pass this pointer on to this callback function when calling it. The information addressed by this pointer is private to WorkFrame/2 processing and is not to be used by PAM-provided functions. ═══ Parameter - pszLine ═══ pszLine (PSZ) - input Address of the string buffer containing the data to be echoed to the Monitor listbox. A newline character ('\n') within the string starts a new line in the Monitor listbox. ═══ Return Values - WKF_ADDMONITOR ═══ (APIRET) - return values WKF_ADDMONITOR returns the following values: 0 NOERROR Line was displayed successfully. Other OS/2*-defined return code. ═══ Notes - WKF_ADDMONITOR ═══ This callback function writes output lines to the Monitor window. It is passed to the WkfRun API so that it can echo stream output to the Monitor window listbox. WkfRun is expected to capture all STDOUT and STDERR stream output and pass it on to this callback function. ═══ Example - WKF_ADDMONITOR ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.4. WkfQueryHAM ═══ WkfQueryHAM Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryHAM ═══ This PAM-provided function is expected to return a caller-unique HAM value to initialize the PAM for the given project. This function is also called to free a HAM value. #define INCL_WKFPAM #include typedef HAM APIENTRY WKF_QUERYHAM ( HAM hamOld, /* Previously set HAM value or NULL */ PSZ pszProjectName /* New project name to assign HAM to, or NULL */ ); typedef WKF_QUERYHAM *PWKF_QUERYHAM; ═══ Parameter - hamOld ═══ hamOld (HAM) - input If this field is not NULL, it contains the previously set HAM value. If this field is NULL on entry, then there was no previously assigned HAM value for this project. The returned HAM will then be assigned. ═══ Parameter - pszProjectName ═══ pszProjectName (PSZ) - input Name of project to assign new HAM to, or NULL. If this pointer is NULL, and hamOld is not NULL, then the previously set HAM should be freed. ═══ Return Values - WkfQueryHAM ═══ (HAM) - return values WkfQueryHAM returns the following values: NULL If, on entry, pszProjectName was NULL, then a NULL return value indicates that all data associated with the hamOld handle was reset, and the hamOld handle freed. If the pszProjectName was not NULL, then the PAM failed. Other Unique PAM-defined HAM value assigned to all data associated with the pszProjectName project. If, on entry, hamOld was NULL, this return value indicates that a new HAM value was assigned to the pszProjectName project. If hamOld was not NULL then any data associated with hamOld was reset, the hamOld handle freed, and a new HAM assigned to the pszProjectName project. ═══ Notes - WkfQueryHAM ═══ This PAM-provided function is expected to return a caller-unique HAM value assigned by the PAM. The returned HAM value associates an instance of the PAM with the caller. It must be unique to each caller of this function. Typically, the returned HAM is a pointer to an initialized structure holding PAM-specific information. Since the returned HAM is subsequently passed to other PAM functions, the WorkFrame/2* program first calls this function for a project before it calls any other PAM functions. This function is called each time a project is created and when a new PAM is assigned to a project. The purpose of this function is to allow the PAM to allocate and store any data that it needs to keep between PAM calls, and perform any processing required to initialize itself for the project (such as establishing a connection to a remote file server). Storage for information necessary for further processing within the PAM should be allocated in the HAM. For example, the session ID from WkfRun can be stored in the HAM so that when WkfStop is invoked, it can access the HAM to identify the session to be stopped. In this case, the WkfQueryHAM should allocate a field in the HAM structure to hold this information so that when WkfRun is invoked, it can store the session ID in the HAM area. All PAM APIs are called with the HAM value to allow the API's to modify the HAM value as required. This function can also be called (with a NULL pszProjectName field) to de-initialize the PAM for a project. In this case, this function should free the old HAM value, and peform any processing required to de-initialize the PAM for the project (such as disconnecting from the remote server and saving any PAM-specific state data in the project file). The following table summarizes the expected behavior of this function: ┌─────────┬──────────────┬────────────────────┬────────────┐ │HamOld │pszProjectName│ Result │Returns │ │(input) │(input) │ │ │ ├─────────┼──────────────┼────────────────────┼────────────┤ │NULL │project_name │Assign new HAM │Unique HAM │ ├─────────┼──────────────┼────────────────────┼────────────┤ │ham_value│NULL │Free old HAM │NULL │ ├─────────┼──────────────┼────────────────────┼────────────┤ │ham_value│project_name │Free old HAM; assign│Unique HAM │ │ │ │new HAM │ │ └─────────┴──────────────┴────────────────────┴────────────┘ ═══ Example - WkfQueryHAM ═══ The following pseudo-code illustrates how this interface could work for an OS/2* file system: /* Check pszProjectName */ if (pszProjectName == NULL) /* Free hamOld value and exit */ { if (hamOld!=NULLHANDLE) { if ( ((BPAM*)hamOld)->fLockedFileIconCopied ) WinDestroyPointer( ((BPAM*)hamOld)->hptrLockedFile ); free( (PVOID)hamOld ); } return( NULLHANDLE ); } else { if (hamOld!=NULLHANDLE) /* Old ham freed, hew ham assigned */ { /* Existing ham changing project name -- nothing to do */ return( hamOld ); } else /* New ham. Allocate memory to store session info for WkfRun() */ { MYPAM *pMypam; /* Structure to hold session information */ pMypam = malloc( sizeof( MYPAM ) ); if (pMypam) { pMypam->ulSessionID = 0; /* No session started yet */ pMypam->hfWritePipe = 0; /* No session started yet */ : } return( (HAM)pMypam ); /* If the malloc failed, this will correctly return NULL */ } } ═══ 13.2.5. WkfQueryTitle ═══ WkfQueryTitle Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryTitle ═══ This PAM-provided function is expected to provide the PAM title or description. value. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_QUERYTITLE ( HAM hamOwner, /* PAM handle */ ULONG ulTitleMax, /* Size, in bytes, of the pszTitle buffer */ PSZ pszTitle /* Address of the buffer to contain the title string */ ); typedef WKF_QUERYTITLE *PWKF_QUERYTITLE; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input PAM handle of project whose access method title to query. This HAM value is created by the WkfQueryHAM API. ═══ Parameter - ulTitleMax ═══ ulTitleMax (ULONG) - input Maximum size, in bytes, of the buffer pointed to by pszTitle. ═══ Parameter - pszTitle ═══ pszTitle (PSZ) - output Address of the buffer to contain the null-delimited title string. On error, a zero-length string should be returned. ═══ Return Values - WkfQueryTitle ═══ (APIRET) - return values WkfQueryTitle returns the following values: 0 NO_ERROR Title successfully provided. Other Failure ═══ Notes - WkfQueryTitle ═══ This PAM-provided function is expected to return the title or description of this access method. The .DLL filename and description (returned by this function) of the access method for a base project is specified on the Access page of the base project's Settings notebook. ═══ Example - WkfQueryTitle ═══ The following pseudo-code illustrates how this interface could work: /* Update pszTitle with the PAM title */ PSZ pszPAMTitle = "IBM WorkFrame/2 ^ Advanced Project Access Method\0"; if (strlen(pszPAMTitle) <= ulTitleMax) strcpy (pszTitle, pszPAMTitle); else /* PAM title longer than allowed so copy */ /* only until maximum allowed length */ strncpy (pszTitle, pszPAMTitle, ulTitleMax); ═══ 13.2.6. WkfSettings ═══ WkfSettings Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfSettings ═══ This optional PAM-provided function is to provide an options dialog to obtain user-specified PAM settings that can be stored in the project file. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_SETTINGS ( HAM hamOwner, /* PAM handle */ PSZ pszProjectFile, /* Project file name */ HWND hwndParent /* Parent window handle of PAM options dialog */ HWND hwndOwner, /* Owner window handle of PAM options dialog */ ULONG cbMessage, /* Size, in bytes, of the pszMessage buffer */ PSZ pszMessage /* Address of the buffer to contain a returned message */ ); typedef WKF_SETTINGS *PWKF_SETTINGS; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input PAM handle of project for whose access method this function is to show a PAM options dialog. This HAM value is created by the WkfQueryHAM API. ═══ Parameter - pszProjectFile ═══ pszProjectFile (PSZ) - input Address of the ASCIIZ project file name. ═══ Parameter - hwndParent ═══ hwndParent (HWND) - input Set the parent of the PAM options dialog to this window handle. ═══ Parameter - hwndOwner ═══ hwndOwner (HWND) - input Set the owner of the PAM options dialog to this window handle. ═══ Parameter - cbMessage ═══ cbMessage (ULONG) - input This pointer contains the number of bytes allocated for the pszMessage buffer, and thus represents its maximum allowed size. This field is set to the WKFPAM_CCHMAXERROR constant. ═══ Parameter - pszMessage ═══ pszMessage (PSZ) - output Address of the buffer to contain an optional null-delimited message string to be displayed to the user. If the return code is not NO_ERROR, then a PAM-specific message may be returned through this string buffer. If this pointer is not NULL on output, the message string is displayed in an error message box by itself. If an OS/2*-defined error occurs, the message will be appended to the OS/2 error message in an error message box. Set this pointer to NULL if no PAM-specific message is to be displayed. Note: Write this PAM function to check the cbMessage length field prior to writing any data to this string pointer. A a count of zero indicates that the WorkFrame/2 program will not process an output message string. ═══ Return Values - WkfSettings ═══ (APIRET) - return values WkfSettings returns the following values: 0 NO_ERROR Settings dialog successfully displayed. Other Failure. ═══ Notes - WkfSettings ═══ This entry point is optional. If it is present, the base project Settings notebook will enable the Options pushbutton on its Access page. When the user clicks on this pushbutton, this function should display a dialog to acquire and store any user-specified, PAM-specific information. The parent and owner of the PAM options dialog should be set to the hwndParent and hwndOwner window handles, respectively. The dialog itself should be modal, and loaded using the WinDlgBox OS/2* API. For more information on the WinDlgBox API, please refer to the IBM* Developer's Toolkit online PM Reference. Use the Project APIs to write the PAM-specific information to the project file. It is suggested that the PAM DLL module name be used for the application name key when writing information to the project file to reduce the likelihood that another PAM or tool-integrator will use the same key name. ═══ Example - WkfSettings ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.7. WkfQueryFiles ═══ WkfQueryFiles Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryFiles ═══ This PAM-provided function is expected to provide the list of parts that belong to a project. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_QUERYFILES ( HAM hamOwner, /* PAM handle */ PSZ pszMasks, /* Project file masks */ PSZ pszContainers /* Path names to be searched for project parts */ PWKF_ADDFILES pfnAddFiles, /* Callback function for inserting project parts into a project container */ PVOID pvPrivateData, /* Parameter to be passed to the pfnAddFiles callback function */ ULONG cbMessage, /* Size, in bytes, of the pszMessage buffer */ PSZ pszMessage /* Address of the buffer to contain a returned message */ ); typedef WKF_QUERYFILES *PWKF_QUERYFILES; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Handle of the project whose parts to query. This HAM value is created by the WkfQueryHAM API. ═══ Parameter - pszMasks ═══ pszMasks (PSZ) - input Pointer to an ASCIIZ list of project file masks for the project specified by the hamOwner handle. Each file mask in the list string is delimited by a WKF_LIST_DELIM character constant. This list of project file masks is specified in the base project's Settings notebook, on the Source page. ═══ Parameter - pszContainers ═══ pszContainers (PSZ) - input Pointer to an ASCIIZ list of directory path names to be searched for the parts (or files) of the project specified by the hamOwner handle. Each path name in the list string is delimited by a WKF_LIST_DELIM character constant. This list of project containers (or source directories) is specified in the base project's Settings notebook, on the Source page. ═══ Parameter - pfnAddFiles ═══ pfnAddFiles (PWKF_ADDFILES) - input Pointer to a WKF_ADDFILES callback function for inserting file objects into a project container. Call this function as many times as necessary to pass the list of files belonging to the project specified by the hamOwner handle field to the WorkFrame/2* program. Each time this interface calls the pfnAddFiles callback function, the WorkFrame/2 program stores the returned file names in its own allocated storage area. Each time this callback function is invoked, the base project folder does a refresh on its contents. ═══ Parameter - pvPrivateData ═══ pvPrivateData (PVOID) - input A pointer to WorkFrame/2* private information used in the processing of the WKF_ADDFILES callback function. Pass this pointer to the pfnAddFiles function when calling it. The information addressed by this pointer is private to WorkFrame/2 processing and is not to be used by any PAM-provided functions. ═══ Return Values - WkfQueryFiles ═══ (APIRET) - return values WkfQueryFiles returns the following values: 0 NO_ERROR Files successfully passed. Other Failure. ═══ Notes - WkfQueryFiles ═══ The WorkFrame/2* program calls this PAM-provided function to obtain the list of project parts or files that belong to a project. The caller provides a list of containers (paths) to search, and a list of file masks. All the files in the given containers that match any one of the file masks should be returned. Return the list of files to the WorkFrame/2* program by creating a list of WKFPAM_PART elements and passing it to the pfnAddFiles callback function. One list per container (or subdirectory) in the project should be created and passed to the pfnAddFiles callback function. As many calls to pfnAddFiles can be made as necessary to complete the list of parts, however, for performance reasons, the number of call backs should be as small as possible since the base project container view is refreshed each time a call to pfnAddFiles is made. It is the responsibility of this function to allocate and free any storage it uses for the parts list. ═══ Example - WkfQueryFiles ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.8. WkfRun ═══ WkfRun Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfRun ═══ Write this PAM-provided function to execute the given action. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_RUN ( HAM hamOwner, /* PAM handle */ PSZ pszTitle, /* Program title to be used */ PSZ pszProgram, /* Name of executable */ PSZ pszParameters, /* Program parameter string */ char *pcEnvironment, /* Environment block */ PSZ pszStartDir, /* Startup directory */ PSZ pszTermQueueName, /* Termination queue name for returning result codes */ ULONG ulRunMode, /* Mode in which to run action */ PWKF_ADDMONITOR pfnAddMonitor, /* Callback function for inserting output lines into the Monitor window */ PVOID pvPrivateData, /* Parameter to be passed to pfnAddFiles callback function */ ULONG cbMessage, /* Size, in bytes, of pszMessage buffer */ PSZ pszMessage /* Pointer to output message buffer */ ); typedef WKF_RUN *PWKF_RUN; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input PAM handle of the project for which the action is to be executed. This HAM value is created by the WkfQueryHAM API, and can be updated to store relevant information, such as the session ID, about the action to be executed for future reference by other PAM API's (such as WkfStop). ═══ Parameter - pszTitle ═══ pszTitle (PSZ) - input The field is either NULL or the address of the buffer containing the null-delimited program title string. ═══ Parameter - pszProgram ═══ pszProgram (PSZ) - input Pointer to an ASCIIZ string containing the name of the program to be executed, for example, "TOOL.EXE" or "TOOL.CMD". ═══ Parameter - pszParameters ═══ pszParameters (PSZ) - input Address of the ASCIIZ string buffer that contains the command-line parameters for the program to be executed by this interface. ═══ Parameter - *pcEnvironment ═══ *pcEnvironment (char) - input This field is either NULL or the address of an environment string that can be passed to the DosStartSession OS/2* API when starting the program in a new session. The DosStartSession passes this string to the program started in the new session. Non-OS/2 PAMs can use this field as relevant in their own file system. When this field is NULL, the program in the new session should inherit the default environment (e.g. the Shell environment, or its parent's environment). This field is of the same format as the environment field required by the DosExecPgm and DosStartSession OS/2 APIs. That is, each environment string is of the form = . The environment strings are delimited by a null character ('\0'), and the last environment string is followed by two null characters. ═══ Parameter - pszStartDir ═══ pszStartDir (PSZ) - input Address of the buffer that contains the directory in which to start the program. This directory is the project's working directory that is specified on the Target page of the base project's Settings notebook. ═══ Parameter - pszTermQueueName ═══ pszTermQueueName (PSZ) - input Termination queue name to be used for returning result messages as required by the DosStartSession OS/2* API. This field is the address of an ASCIIZ string that contains the fully qualified path and file name of a system queue. Once an OS/2* session is started with the DosStartSession API, specifying this queue, the OS/2 Session Manager will use the queue to send termination notification messages to the parent session. For more information, consult the online publication from the IBM* Developer's Toolkit, Control Program Guide and Reference ═══ Parameter - ulRunMode ═══ ulRunMode (ULONG) - input This field indicates the mode in which to run the specified action. It can contain any one of the following values: 1 WKF_RUNMODE_FULLSCREEN Start the action in a full-screen session. 2 WKF_RUNMODE_WINDOW Start the program in a windowed (vio) session for programs using the Base Video Subsystem. 3 WKF_RUNMODE_MONITOR Start the program in a WorkFrame/2* Monitor window. Use the WKF_ADDMONITOR callback function to write lines of output to the Monitor window. 255 WKF_RUNMODE_DEFAULT Start the program in default run mode. Within the OS/2* system, default mode allows the Shell to establish the session type. The WorkFrame/2* program uses DosStartSession to start programs within the OS/2 system. ═══ Parameter - pfnAddMonitor ═══ pfnAddMonitor (PWKF_ADDMONITOR) - input Use this callback function to write lines of output to the WorkFrame/2* Monitor window if the action is to be started in the Monitor window. This callback function is used only if the ulRunMode field has the value WKF_RUN_MONITOR. If the action is to run in the Monitor window, this interface should capture all stream output (e.g. STDOUT and STDERR ) and pass it on to this callback function. Programs that output in line mode (for example, OS/2* programs that do not use Presentation Manager* services and run in windowed or full-screen mode) are viable candidates to run in the Monitor window. Ideally, these programs should run invisibly in the background, and their output displayed in the Monitor window. ═══ Parameter - pvPrivateData ═══ pvPrivateData (PVOID) - input A pointer to WorkFrame/2*-private information used in the processing of the WKF_ADDMONITOR callback function. Pass this pointer to the pfnAddMonitor function when calling it. The information addressed by this pointer is private to WorkFrame/2 processing and is not to be used by any PAM-provided functions. ═══ Return Values - WkfRun ═══ (APIRET) - return values WkfRun returns the following values: 0 NO_ERROR Action successfully invoked without errors. Other OS/2*-defined return code. ═══ Notes - WkfRun ═══ The WorkFrame/2* program calls this PAM-provided function to execute an action. The name of the program executable, parameters to use, environment block, startup directory, and run mode are passed into this interface by the WorkFrame/2 program. The program to run may be an OS/2*-native program, or a remote command. This interface should check that the given program is a valid executable within the file system that this PAM provides access for. The specified program should be run from the startup directory identified by the pszStartDir field. If the program is to run in the Monitor window (that is, if the ulRunMode field is set to WKF_RUNMODE_MONITOR), this interface should not return until the started process has completed. By contrast, if the program is not to run in the Monitor window, this interface should return immediately after the process has been launched. OS/2 PAMs should use the DosStartSession system API to start the program. The Basic Project Access Method (bPAM) shipped with the WorkFrame/2 program contains methods for running OS/2, DOS, and WINOS2 programs within any OS/2 native environments, or from within the monitor. ═══ Example - WkfRun ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.9. WkfStop ═══ WkfStop Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfStop ═══ Write this PAM-provided function to stop a running process started through WkfRun. #define INCL_WKFPAM #include typedef APIRET APIENTRY WKF_STOP ( HAM hamOwner, /* PAM handle */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_STOP *PWKF_STOP; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input PAM handle of the project for which the action was started. This HAM value is created by the WkfQueryHAM API, and contains information that identifies the running session to be aborted. ═══ Return Values - WkfStop ═══ (APIRET) - return values WkfStop returns the following values: 0 NO_ERROR Process successfully halted. Other OS/2*-defined return code. ═══ Notes - WkfStop ═══ The WorkFrame/2* program calls this PAM-provided function to stop the running process started through the WkfRun API. The hamOwner field contains PAM-specific information that uniquely identifies the process to be aborted. The hamOwner field is the unique HAM value that is returned by the WkfQueryHAM API. OS/2* processes can be stopped using the DosStopSession system API. For more information, consult the online publication from the IBM* Developer's Toolkit, Control Program Guide and Reference ═══ Example - WkfStop ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.10. WkfQueryPathInfo ═══ WkfQueryPathInfo Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryPathInfo ═══ Write this PAM-provided function to indicate whether or not a given path is valid for this PAM's file system. #define INCL_WKFPAM #include #define WKF_PFS_QPATHINFO "WKFQUERYPATHINFO" typedef APIRET APIENTRY WKF_QPATHINFO ( HAM hamOwner, /* PAM handle */ PSZ pszPathName, /* Path name to be validated */ ULONG ulFullPathBufSize, /* Size of pszFullPathName buffer */ PSZ pszFullPathName, /* Pointer to output buffer to contain fully qualified path name, if valid */ BOOL *pfExists, /* Path exists flag */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_QPATHINFO *PWKF_QPATHINFO; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszPathName ═══ pszPathName (PSZ) - input Address of the ASCIIZ buffer containing the path name to be validated. This path may or may not contain a file name, and may contain characters that this PAM's file system can recognize. For example, the ".." characters in OS/2* refer to the parent directory of the current subdirectory; "\" refers to the root directory. ═══ Parameter - ulFullPathBufSize ═══ ulFullPathBufSize (ULONG) - input This pointer contains the number of bytes allocated for the pszFullPathName buffer, and thus represents its maximum allowed size. Currently, this field is set to the OS/2*-defined constant, CCHMAXPATH. ═══ Parameter - pszFullPathName ═══ pszFullPathName (PSZ) - output On exit, this field should contain the fully specified name of the path specified by the pszPathName field, if it is a valid path name this PAM's file system. ═══ Parameter - *pfExists ═══ *pfExists (PSZ) - output On exit, this field should be set to TRUE if the file identified by the pszPathName field actually exists, FALSE if it does not. ═══ Return Values - WkfQueryPathInfo ═══ (APIRET) - return values WkfQueryPathInfo returns the following values: 0 NO_ERROR Path name successfully validated Other OS/2*-defined return code. ═══ Notes - WkfQueryPathInfo ═══ The WorkFrame/2* program calls this PAM-provided function to test whether the path name identified by the pszPathName field is valid within this PAM's file system. The pszPathName field can contain any part of a path name. This function is expected to update the pszFullPathName field with the fully qualified path name, if the given path is valid. Note that the path does not have to exist for it to be valid. For example, if one of this project's source directories is C:\MYPROJ\DLL\MAK , and pszPathName contains the partial path \DLL\MAK\MAKEFILE.MAK , this function should update the pszFullPathName field with the fully qualified path string (which, in this case is "C:\PROJ\DLL\MAK\MAKEFILE.MAK" ) if the pszPathName path is a valid path name in this PAM's file system. If the path actually exists, the *pfExists field should be set to TRUE, otherwise, it should be set to FALSE. ═══ Example - WkfQueryPathInfo ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.11. WkfCreatePath ═══ WkfCreatePath Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfCreatePath ═══ Write this PAM-provided function to create all nodes (or subdirectories) along the specified path. #define INCL_WKFPAM #include #define WKF_PFS_CREATEPATH "WKFCREATEPATH" typedef APIRET APIENTRY WKF_CREATEPATH ( HAM hamOwner, /* PAM handle */ PSZ pszPath, /* Path to be created */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_CREATEPATH *PWKF_CREATEPATH; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszPath ═══ pszPath (PSZ) - input Address of the ASCIIZ buffer containing the path to create. ═══ Return Values - WkfCreatePath ═══ (APIRET) - return values WkfCreatePath returns the following values: 0 NO_ERROR All nodes along the specified path successfully created Other OS/2*-defined return code. ═══ Notes - WkfCreatePath ═══ The WorkFrame/2* program calls this PAM-provided function to create all nodes along the path specified by the pszPath field. In the OS/2* file system, a node is a subdirectory. For example, if the pszPath field contained the string "C:\MYPROJ\HEADERS\GENERAL", this function should create the subdirectories \MYPROJ , \MYPROJ\HEADERS , and \MYPROJ\HEADERS\GENERAL on the C:\ drive. If one or more nodes along the given path already exists, ignore them. Create only those nodes that do not already exist. If the given path is not fully qualified (for example, if it is missing a drive letter), create the nodes beneath the current directory. ═══ Example - WkfCreatePath ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.12. WkfQueryCopy ═══ WkfQueryCopy Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryCopy ═══ Write this PAM-provided function to indicate whether files can be copied into the current container. #define INCL_WKFPAM #include #define WKF_PFS_QCOPY "WKFQUERYCOPY" typedef APIRET APIENTRY WKF_QCOPY ( HAM hamOwner, /* PAM handle */ PSZ pszFile, /* Object to be copied */ PSZ pszTargetPath, /* Proposed path to copy object to */ PULONG pulMove, /* Indicates whether object can be moved, copied, either, or neither */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_QCOPY *PWKF_QCOPY; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszFile ═══ pszFile (PSZ) - input Address of the ASCIIZ buffer containing the fully qualified path of the file to be copied. ═══ Parameter - pszTargetPath ═══ pszTargetPath (PSZ) - input Address of the ASCIIZ buffer containing the fully qualified target path to which the object identified by the pszFile field is to be copied to. ═══ Parameter - pulMove ═══ pulMove (PULONG) - output On exit, this field should contain one of the following values: WKF_NOCOPY Copy or move not allowed. WKF_MOVEFILES Only move allowed. Copy file and delete original. WKF_COPYFILES Only copy allowed. Original file must be kept. WKF_CREATEFILES Create file from template. WKF_MOVEFILESREPL Move file and replace duplicate at target container without checking. WKF_COPYFILESREPL Copy file and replace duplicate at target container without checking. WKF_CREATEFILESREPL Create file from template and replace duplicate at target container without checking. ═══ Return Values - WkfQueryCopy ═══ (APIRET) - return values WkfQueryCopy returns the following values: 0 NO_ERROR Copy operation verified successfully. Other OS/2*-defined return code. ═══ Notes - WkfQueryCopy ═══ The WorkFrame/2* program calls this function to determine whether the requested file can be copied or moved into the project. Typically, this interface is called prior to performing the actual copy or move to ensure that there is sufficient permission to perform such an operation. If NO_ERROR is returned, then it is assumed that the copy or move function can proceed. This function may be called as part of the processing of a DM_DRAGOVER OS/2* message across a base project container view. ═══ Example - WkfQueryCopy ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.13. WkfCopyFile ═══ WkfCopyFile Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfCopyFile ═══ Write this PAM-provided function to copy or move a file between containers that use the same PAM. #define INCL_WKFPAM #include #define WKF_PFS_COPYFILE "WKFCOPYFILE" typedef APIRET APIENTRY WKF_COPYFILE ( HAM hamOwner, /* PAM handle */ PSZ pszPathFrom, /* Source path from which file is to be copied */ PSZ pszFileFrom, /* Name of object to be copied */ PSZ pszPathTo, /* Target path to which file it so be copied */ PSZ pszFileTo, /* Target file name */ ULONG ulMove, /* Indicates whether object is to be moved or copied */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_COPYFILE *PWKF_COPYFILE; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszPathFrom ═══ pszPathFrom (PSZ) - input Address of the ASCIIZ buffer that may contain the source path from which to copy the file identified by the pszFileFrom field. Note: This field is not guaranteed to contain only the source path name. It could be NULL (in which case pszFileFrom contains the fully-qualified name of the file to be copied), or it could contain the fully-qualified path name of the file to be copied (in which case pszFileFrom is NULL). Append the pszFileFrom field to this field to obtain the fully-qualified path name of the file to be copied. ═══ Parameter - pszFileFrom ═══ pszFileFrom (PSZ) - input Address of the ASCIIZ buffer that may contain the name of the file to be copied. Note: This field is not guaranteed to contain only the source file name. It could be NULL (in which case pszPathFrom contains the fully-qualified name of the file to be copied), or it could contain the fully-qualified path name of the file to be copied (in which case pszPathFrom is NULL). Append this field to the pszPathFrom field to obtain the fully-qualified path name of the file to be copied. ═══ Parameter - pszPathTo ═══ pszPathTo (PSZ) - input Address of the ASCIIZ buffer that may contain the target path to which to copy the file. Note: This field is not guaranteed to contain only the target path name. It could be NULL (in which case pszFileTo contains the fully-qualified name of the file to copy to), or it could contain the fully-qualified path name of the file to copy to (in which case pszFileTo is NULL). Append the pszFileTo field to this field to obtain the fully-qualified path name of the target file to copy to. ═══ Parameter - pszFileTo ═══ pszFileTo (PSZ) - input Address of the ASCIIZ buffer that may contain the name that the file is to be given after it is copied to the identified by the pszPathTo destination container. Note: This field is not guaranteed to contain only the unqualified target file name. It could be NULL (in which case pszPathTo contains the fully-qualified name of the file to copy to), or it could contain the fully-qualified path name of the file to copy to (in which case pszPathTo is NULL). Append this field to the pszPathTo field to obtain the fully-qualified path name of the target file to copy to. ═══ Parameter - ulMove ═══ ulMove (ULONG) - input This field indicates whether the file is to be moved or copied. It can contain any one of the following values: WKF_MOVEFILES Move the specified file; copy file and delete original. WKF_COPYFILES Copy the specified file; keep original file. WKF_MOVEFILESREPL Move file and replace duplicate at target container without checking. WKF_COPYFILESREPL Copy file and replace duplicate at target container without checking. ═══ Return Values - WkfCopyFile ═══ (APIRET) - return values WkfCopyFile returns the following values: 0 NO_ERROR Copy operation performed successfully. Other OS/2*-defined return code. ═══ Notes - WkfCopyFile ═══ The WorkFrame/2* program calls this function to copy or move a file from one container (or directory) to another. The source and target containers can belong to different projects, but the WorkFrame/2 program verifies that they use the same PAM. This function can also be called to create a file from a template, such as the OS/2* Data File template in the Templates folder. ═══ Example - WkfCopyFile ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.14. WkfDelete ═══ WkfDelete Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfDelete ═══ Write this PAM-provided function to delete a specified file. #define INCL_WKFPAM #include #define WKF_PFS_DELETE "WKFDELETE" typedef APIRET APIENTRY WKF_DELETE ( HAM hamOwner, /* PAM handle */ PSZ pszPath, /* Source path from which file is to be deleted */ PSZ pszFile, /* Name of object to be deleted */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_DELETE *PWKF_DELETE; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszPath ═══ pszPath (PSZ) - input Address of the ASCIIZ buffer that may contain the container (or subdirectory) from which to delete the file. Note: This field is not guaranteed to contain only the path name of the directory from which the file is to be deleted. It could be NULL (in which case pszFile contains the fully-qualified name of the file to be deleted), or it could contain the fully-qualified path name of the file to be deleted (in which case pszFile is NULL). Append the pszFile field to this field to obtain the fully-qualified path name of the file to be deleted. ═══ Parameter - pszFile ═══ pszFile (PSZ) - input Address of the ASCIIZ buffer that may contain the unqualified name of the file to be deleted. Note: This field is not guaranteed to contain only the unqualified file name of the file to be deleted. It could be NULL (in which case pszPath contains the fully-qualified name of the file to be deleted), or it could contain the fully-qualified path name of the file to be deleted (in which case pszPath is NULL). Append this field to the pszPath field to obtain the fully-qualified path name of the file to be deleted. ═══ Return Values - WkfDelete ═══ (APIRET) - return values WkfDelete returns the following values: 0 NO_ERROR Deletion performed successfully. Other OS/2*-defined return code. ═══ Notes - WkfDelete ═══ The WorkFrame/2* program calls this function to delete a specified file. ═══ Example - WkfDelete ═══ The following pseudo-code illustrates how this interface could work: @@@@@ ═══ 13.2.15. WkfDefaultName ═══ WkfDefaultName Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfDefaultName ═══ Write this PAM-provided function to return the default make file or target file name. #define INCL_WKFPAM #include #define WKF_PFS_DEFAULTNAME "WKFDEFAULTNAME" typedef APIRET APIENTRY WKF_DEFAULTNAME ( HAM hamOwner, /* PAM handle */ PSZ pszPrjFileName, /* Project file name */ ULONG ulRequestFlag, /* Indicates which default name to return */ ULONG cbDefault, /* Size of pszDefault buffer */ PSZ pszDefault, /* Address of buffer to contain default name requested */ ULONG cbMessage, /* Size of message buffer */ PSZ pszMessage /* Pointer to message buffer */ ); typedef WKF_DEFAULTNAME *PWKF_DEFAULTNAME; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszPrjFileName ═══ pszProjectFileName (PSZ) - input Address of the ASCIIZ buffer containing the project file name associated with the HAM value specified by the hamOwner field. ═══ Parameter - ulRequestFlag ═══ ulRequestFlag (ULONG) - input This field indicates which default file name to return. It can any one of the following values: WKF_DNAME_MAKE Return the default makefile name in the pszDefault field. WKF_DNAME_TARGET Return the default target file name in the pszDefault field. ═══ Parameter - cbDefault ═══ cbDefault (ULONG) - input This pointer contains the number of bytes allocated for the pszDefault buffer, and thus represents its maximum allowed size. ═══ Parameter - pszDefault ═══ pszDefault (PSZ) - output On exit, this buffer should contain the default makefile name if the ulRequestFlag is set to WKF_DNAME_MAKE. If ulRequestFlag is set to WKF_DNAME_TARGET, this buffer should contain the default target name. ═══ Return Values - WkfDefaultName ═══ (APIRET) - return values WkfDefaultName returns the following values: 0 NO_ERROR Default name returned with no error. Other OS/2*-defined return code. ═══ Notes - WkfDefaultName ═══ The WorkFrame/2* program calls this function to determine the default makefile name or the default target file name for the project identified by the pszPrjFileName field. The ulRequestFlag field indicates which default file name to return. For example, the make file and target file names could be obtained from the project name. For example, if the project name is "Hello World", the default make file name could be "HELLOWOR.MAK", and the default target file name could be "HELLOWOR.EXE". ═══ Example - WkfDefaultName ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 13.2.16. WkfQueryRunnable ═══ WkfQueryRunnable Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryRunnable ═══ Write this PAM-provided function to indicate whether or not a given file is a valid executable. #define INCL_WKFPAM #include #define WKF_PFS_QRUNNABLE "WKFQUERYRUNNABLE" typedef BOOL APIENTRY WKF_QRUNNABLE ( HAM hamOwner, /* PAM handle */ PSZ pszContainer, /* Source path of file to verify */ PSZ pszFilename /* Name of file to verify */ ); typedef WKF_QRUNNABLE *PWKF_QRUNNABLE; ═══ Parameter - hamOwner ═══ hamOwner (HAM) - input Project PAM handle created by the WkfQueryHAM API. ═══ Parameter - pszContainer ═══ pszContainer (PSZ) - input Address of the ASCIIZ buffer that may contain the path containing the file to be verified. Note: This field is not guaranteed to contain only the path name of the directory of the file to be verified. It could be NULL (in which case pszFilename contains the fully-qualified name of the file to be verified), or it could contain the fully-qualified path name of the file to be verified (in which case pszFilename is NULL). Append the pszFilename field to this one to obtain the fully-qualified path name of the file to be verified. ═══ Parameter - pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ buffer that may contain the name of the file to be verified. Note: This field is not guaranteed to contain only the unqualified name of the file to be verified. It could be NULL (in which case pszContainer contains the fully-qualified name of the file to be verified), or it could contain the fully-qualified path name of the file to be verified (in which case pszContainer is NULL). Append the this field to the pszCOntainer field to obtain the fully-qualified path name of the file to be verified. ═══ Return Values - WkfQueryRunnable ═══ (BOOL) - return values WkfQueryRunnable returns the following values: TRUE Specified file is a valid executable. FALSE Specified file is not a valid executable and cannot be run. ═══ Notes - WkfQueryRunnable ═══ The WorkFrame/2* program calls this function to determine whether a file is a valid executable in the file system this PAM provides access to. For example, in the OS/2* system, files ending with the extensions .BAT, .CMD, .EXE, and .BAT are runnable. Files ending with the extensions .DLL and .OBJ are not. ═══ Example - WkfQueryRunnable ═══ The following pseudo-code illustrates how this interface could work: @@@@@@ ═══ 14. Projects ═══ This section discusses: 1. The use of OS/2* APIs to create, set, and query project objects 2. The WorkFrame/2-provided functions that facilitate reading and writing to a base project file. ═══ 14.1. Using the Project APIs ═══ The WorkFrame/2* project interfaces facilitate reading and writing to a base project file. Currently there are no such interfaces for composite projects. Composite project settings can only be queried and changed through OS/2* APIs. Composite and base project objects are created, set, and deleted using the OS/2* APIs WinCreateObject, WinSetObjectData, and WinDestroyObject. See Managing Project Objects for more information. Call the WkfOpenProjectFile interface before using any of the other project file APIs. This interface prepares the project file for writing or querying. The base project file contains two kinds of information: 1. Public information that is common to all projects. This information is present in the base project's Settings notebook and can be set using the WinSetObjectData OS/2* API, and read using the WkfReadProject interface. 2. Private, tool-specific information. The WkfWriteProjectData and WkfQueryProjectData interfaces enable tools to store and retrieve project-related information specific to a tool. Access to tool-specific project file data is provided using a two-level key framework. A single piece of data is indexed on two keys, an application name key and a data key. Thus, any piece of project data can be accessed using the key-name pair, . Application and data key names are arbitrary strings chosen by the tool integrator. When choosing key names for project data, follow these guidelines: o The application and data key names should not start with the prefixes DDE3, WKF, or PM_ as these are reserved for WorkFrame/2 and OS/2 system data. o Choose the application name to uniquely identify the tool that owns the data. To minimize the chances of another tool using the same key name, the application name should include a unique company identifier, the tool name, and perhaps the tool's version number. For example, IBM_CSET_V2 could identify the IBM* C Set ++ Version 2.0 product. o The application and data key names should not be longer than CCHMAXPATH. o The application key name should also be specified in upper-case when querying project data since it is automatically converted to upper-case before being written to the project file. ═══ 14.2. Managing Project Objects ═══ This section discusses the use of the OS/2* APIs WinCreateObject, WinSetObjectData, and WinDestroyObject to create and delete WorkFrame/2* project desktop objects. These topics are covered: o Creating projects o Setting project data o Deleting projects. Note: Any operations performed on WorkFrame/2* objects (such as projects and actions profiles) that are not accomplished using the WorkFrame/2 integration APIs, are not guaranteed to be compatible in future versions of WorkFrame/2. APIs to set, create, and delete projects will be made available in future versions. See the Copyright Notice for more information. ═══ 14.2.1. Creating Projects ═══ WorkFrame/2* Version 2.1 base and composite project objects are created using the WinCreateObject OS/2* API. This section covers the following topics: 1. Creating a base project 2. Creating a composite project. ═══ 14.2.1.1. Creating a Base Project ═══ To create a base project, call WinCreateObject specifying "DDE3Project" for the object's SOM class, and the correct keyname-value pairs in the setup string. Following is an example of how to create a base project: hProject = WinCreateObject ( "DDE3Project", /* Base project class name */ "Sample Base Project", /* Base project title */ pszSetupString, /* Setup string */ "C:\\Desktop\\Projects", /* Create object in this folder */ CO_REPLACEIFEXISTS); /* Creation flags */ The above call to WinCreateObject creates a base project with the title "Sample Base Project", in the folder called "Projects". The creation flag indicates that the base project should be replaced if it already exists. The project's object handle is returned. If you wanted to create the project in the WorkFrame/2 Samples folder, you could have specified its persistent object ID as the fourth parameter of WinCreateObject See Persistent Object IDs for a list of WorkFrame/2 object IDs. The required setup string consists of a series ofkeyname-value pairs, defined for the class, that initialize the object. Keynames are separated by semicolons, and values are separated by commas, as in: "key=value; key2=value1,value2;" For example, you could build a base project set up string like this: pszSrcDirs = "C:\\TOOL\nC:\\UTILS"; pszProfile = "C:\\DESKTOP\\IBMWFV21\\ACTIONSP\\SAMPLEAC.PRF"; j = sprintf (pszSetupString, WKF_PJIOKEY_DIR"=%s;"WKF_PJIOKEY_PROFILE"=%s", pszSrcDirs, pszProfile); The following table shows the keyname-value pairs supported by the "DDE3Project" class: ┌─────────────────────────┬─────────────────────────────────┬────────────────────────────────────────────┐ │Keyname (string constant)│Value (string constant or │Description │ │ │literal) │ │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_DIR │List of project directory path │This sets the project directories, and is │ │ │names, each separated by a │equivalent to specifying the project │ │ │newline (\n) character. │directories in the Source page of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_EXECACTION │Action class name │This sets the default open behavior for │ │ │ │executable files, and is equivalent to │ │ │ │specifying it on the Actions pages of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_FILEMENU │WKF_PJIOMENU_SHORT │This sets the project's file-scoped actions │ │ │ │menu to include only the actions that belong│ │ │ │on a Regular menu. This is equivalent to │ │ │ │selecting the Regular menu type option on │ │ │ │the file-scoped Actions page of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOMENU_DETAILED │This sets the project's file-scoped actions │ │ │ │menu to include only the actions that belong│ │ │ │on an Extended menu. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_MAKEFILE │Default make file name │This sets the default make file name that is│ │ │ │used when an action of the MAKE class is │ │ │ │invoked on the project or its parts. This │ │ │ │is equivalent to specifying the make file │ │ │ │name on the Target page of the project's │ │ │ │Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_MASK │List of file masks, each │This sets the file masks for the project, │ │ │separated by a newline (\n) │and is equivalent to specifying the file │ │ │character. │masks on the Source page of the project's │ │ │ │Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_MONITOR │WKF_PJIOMON_AUTOCLOSE │This sets the Monitor window to close itself│ │ │ │if the associated action ends with a return │ │ │ │code of zero. This is equivalent to │ │ │ │selecting the Multiple concurrent monitors │ │ │ │option on the Monitor page of the base │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOMON_MINIMIZE │This sets the Monitor window to start │ │ │ │actions for the project in a minimized │ │ │ │state. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOMON_NOMULTIPLE │This resets the Monitor window to run │ │ │ │actions for the project one after another, │ │ │ │instead of in multiple, concurrent Monitor │ │ │ │windows. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_OPENACTION │Action class name │This sets the default open behavior for │ │ │ │non-executable files, and is is equivalent │ │ │ │to specifying it on the Actions pages of the│ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_PAM │Project access method │This sets the project access method, and is │ │ │ │equivalent to specifying the PAM in the │ │ │ │Access page of the project's Settings │ │ │ │notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_PATHNAME_ADDR│Address of an allocated │On a successful return from a call to │ │ │shared-memory buffer to hold the │WinCreateObject to create the project, the │ │ │returned project file name. │buffer is updated to contain the │ │ │ │fully-qualified project file name. You will│ │ │ │need the project filename to store │ │ │ │tool-specific data in the project file (see │ │ │ │WkfWriteProjectData for more information). │ │ │ │The buffer needs to be allocated using │ │ │ │DosAllocSharedMem, with a size of CCHMAXPATH│ │ │ │and the following flags set: PAG_COMMIT | │ │ │ │OBJ_GETTABLE | PAG_READ | PAG_WRITE │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_PROFILE │Fully qualified file name of an │This sets the actions profile to use for the│ │ │actions profile, upper-cased. │project. This is equivalent to specifying │ │ │ │the profile in the Profile page of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_PROJECTMENU │WKF_PJIOMENU_SHORT │This sets the project's project-scoped │ │ │ │actions menu to include only the actions │ │ │ │that belong on a Regular menu. This is │ │ │ │equivalent to selecting the Regular menu │ │ │ │type option on the project-scoped Actions │ │ │ │page of the project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOMENU_DETAILED │This sets the project's project-scoped │ │ │ │actions menu to include only the actions │ │ │ │that belong on an Extended menu. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_TARGETNAME │Target program file name │This sets the target program file name, and │ │ │ │is equivalent to specifying it in the Target│ │ │ │page of the project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_TARGETPARM │Target program parameters │This sets the target program parameters to │ │ │ │run the target program with when it is │ │ │ │invoked. This is equivalent to specifying │ │ │ │the parameters in the Target page of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_TARGETPATH │Working directory │This sets the working directory for the │ │ │ │project. This directory is used (1) to │ │ │ │store the make file created by MakeMake, (2)│ │ │ │to store files copied from other Workplace │ │ │ │Shell objects, and (3) as the current │ │ │ │directory when actions are selected on │ │ │ │behalf of the project or any of its parts. │ │ │ │This is equivalent to specifying the working│ │ │ │directory in the Target page of the │ │ │ │project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_TARGETPROMPT │WKF_PJIOVALUE_TRUE │This sets the project to display a prompt │ │ │ │for entering parameters when its target │ │ │ │program is run. This is equivalent to │ │ │ │selecting the Prompt required checkbox on │ │ │ │the Target page of the project's Settings │ │ │ │notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOVALUE_FALSE │This resets the prompt required flag for the│ │ │ │project's target program. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │WKF_PJIOKEY_TARGETTYPE │WKF_PJIOPROG_WINDOW │This sets the target program to run in a │ │ │ │windowed (vio) session, and is equivalent to│ │ │ │setting the run mode to Window on the Target│ │ │ │page of the project's Settings notebook. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOPROG_MONITOR │This sets the target program to run in a │ │ │ │WorkFrame/2 Monitor window. │ ├─────────────────────────┼─────────────────────────────────┼────────────────────────────────────────────┤ │ │WKF_PJIOPROG_FULLSCREEN │This sets the target program to run in a │ │ │ │full screen session. │ └─────────────────────────┴─────────────────────────────────┴────────────────────────────────────────────┘ Notes 1. All keynames, except for that represented by WKF_PJIOKEY_DIR, have safe default values so it is never required to include all the possible keyname-value pairs in the setup string. 2. The project creator is responsible for keeping track of the project file name, as it is a required parameter for the base project APIs. 3. Since the "DDE3Project" class is subclassed from the "WPFileSystem" Workplace Shell class, keyname=values pairs defined for "WPFileSystem" are also valid for "DDE3Project". See the online PM Reference from IBM* Developer's Toolkit for more information on Workplace Shell classes and the WinCreateObject API. ═══ 14.2.1.2. Creating a Composite Project ═══ To create a composite project, call WinCreateObject specifying "DDE3Folder" for the object's SOM class, and the correct keyname-value pairs in the setup string. Following is an example of how to create a composite project: hCompositePrj = WinCreateObject ("DDE3Folder", /* Composite project class Name */ "Sample Composite Project", /* Composite project title */ pszSetupString, /* Setup string */ , /* Create object in WF Samples folder*/ CO_REPLACEIFEXISTS); /* Creation flags */ The above call to WinCreateObject creates a base project with the title "Sample Composite Project" in the WorkFrame/2 Samples folder. The project's object handle is returned. Since the "DDE3Folder" class is subclassed from "WPFolder", it inherits the defined setup string keyname-value pairs from "WPFolder", and adds two of its own: ┌──────────────────────┬────────────────────────────────────────┬────────────────────────────────────────┐ │Keyname (string │Value │Description │ │constant) │ │ │ ├──────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤ │WKF_PRJF_SEQUENCE │List of project titles, each separated │This sets the composite project's │ │ │by a newline (\n) character. For │project sequence, which determines the │ │ │example: │sequence in which an action that is │ │ │"My Project\nMy Utilities" │invoked on the composite project is │ │ │ │applied to each sub-project. This is │ │ │ │equivalent to specifying the project │ │ │ │sequence on the Sequence page of the │ │ │ │composite project's Settings notebook. │ ├──────────────────────┼────────────────────────────────────────┼────────────────────────────────────────┤ │WKF_PRJF_TARGET │Target project title. For example: │This sets the composite project's target│ │ │"My Very Own Project" │project. The target project specifies │ │ │ │(1) the project to which files are │ │ │ │copied or moved to, and (2) the project │ │ │ │that contains the executable file to be │ │ │ │started when Open  Target project is │ │ │ │selected from the composite project's │ │ │ │system menu. This is equivalent to │ │ │ │specifying the target project on the │ │ │ │Target page of the composite project's │ │ │ │Setting's notebook. │ └──────────────────────┴────────────────────────────────────────┴────────────────────────────────────────┘ See the online PM Reference from IBM* Developer's Toolkit for more information on the "DDE3Folder" Workplace Shell class and the WinCreateObject API. ═══ 14.2.2. Setting and Querying Project Data ═══ Base Projects There are two kinds of data stored in a base project file: 1. Public data that is common to all base projects, such as source directories, masks, and project access method. You can retrieve public base project data with the WkfReadProject API. Set public project data by invoking the WinSetObjectData OS/2* API with the project handle returned by WinCreateObject when the object was created, or the project handle obtained via WinQueryObject. WinSetObjectData expects a setup string containing the keyword-value pairs that you want to change. For example, to change the actions profile for a base project, you might issue this function call: pszProfile = "C:\\DESKTOP\\MYFOLDER\\MYPROFIL.PRF"; j = sprintf (pszSetupString, WKF_PJIOKEY_PROFILE"=%s", pszProfile); fSuccess = WinSetObjectData (hProject, /* Project handle from WinCreateObject or WinQueryObject */ pszSetupString); /* Setup string */ 2. Project data that is private to a tool. This data is stored and retrieved using the WkfWriteProjectData and WkfQueryProjectData APIs. Composite Projects Composite projects have public data as well, (namely, target project and project sequence), but they cannot contain tool-specific data. Composite project data is set using the WinSetObjectData OS/2* API, as with base projects. Currently, there is no means to query composite project data. The notion of a composite project will not be supported in future releases of WorkFrame/2 See the Copyright Notice for more information. See the online PM Reference from IBM* Developer's Toolkit for more information on OS/2 APIs and Workplace Shell methods. ═══ 14.2.3. Deleting Projects ═══ Both base and composite projects can be permanently deleted using the OS/2* WinDestroyObject API. For example: fSuccess = WinDestroyObject (hProject); /* Project's object handle */ See the online PM Reference from IBM* Developer's Toolkit for more information on the WinDestroyObject API. ═══ 14.3. Base Project APIs ═══ This section describes the WorkFrame/2*-supplied functions for querying and setting base project information. The function prototypes and message definitions for the router APIs are in the WKFPRJ.H C header file. ═══ 14.3.1. WkfOpenProjectFile ═══ WkfOpenProjectFile Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfOpenProjectFile ═══ This WorkFrame/2*-provided function opens a base project file for read or write access. #define INCL_WKFPRJ #include LHANDLE APIENTRY WkfOpenProjectFile ( HAB hab, /* Caller's anchor block handle */ PSZ pszFileName, /* Project's fully qualified file name */ ULONG ulMode /* Access and share modes */ ); ═══ Parameter - hab ═══ hab (HAB) - input The caller's anchor block handle (optional). If a NULLHANDLE is passed, then the desktop's anchor block is used. ═══ Parameter - pszFileName ═══ pszFileName (PSZ) - input The fully qualified name of the project file to open. If the project file does not exist, it will be created. Ensure that the project file is correctly associated with the intended project object. See Setting and Querying Project Data for more information. ═══ Parameter - ulMode ═══ ulMode (ULONG) - input Access and share modes. This field us currently ignored in WorkFrame/2* version 2.x, however, it is recommended that these modes be set for future compatibility. Set this field to one or more of the following flags combined using the bitwise-OR (|) operator: WKF_ACCESS_READ Open project file with read-only access WKF_ACCESS_ALL Open project file with read and write access WKF_SHARE_DENYNONE Allow others to open project file while caller has access WKF_SHARE_DENYWRITE Allow only read access to others while caller has access WKF_SHARE_DENYALL Request exclusive access to project file. ═══ Return Values - WkfOpenProjectFile ═══ (LHANDLE) - return values WkfOpenProjectFile returns the following values: NULLHANDLE Unable to open project file. The specified project file may already be accessed by another process, or there may not be enough disk space. Other Project file successfully opened. Project handle is returned. Use this handle to close the project using WkfCloseProjectFile. ═══ Notes - WkfOpenProjectFile ═══ This WorkFrame/2-provided function opens a project file for read or write access. It must be called before any other project interface. This function returns a project handle that uniquely identifies the caller's access to the project file. The project handle is required as input to other project APIs, such as WkfCloseProjectFile. ═══ Example - WkfOpenProjectFile ═══ The following pseudo-code illustrates how this interface could be used: /* Open project file for reading */ pszPrjFilename = "C:\\DESKTOP\\PROJECTS\\MY PROJECT"; hProject = WkfOpenProjectFile ( NULLHANDLE, /* Just use desktop's hab */ pszPrjFilename, WKF_ACCESS_READ); ═══ 14.3.2. WkfReadProject ═══ WkfReadProject Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfReadProject ═══ This WorkFrame/2*-provided function reads base project information from an open project file. #define INCL_WKFPRJ #include APIRET APIENTRY WkfReadProject ( PSZ pszFileName, /* Project's fully qualified file name */ PWKFBASEPROJECT pPrjInfo /* Pointer to project info structure */ ); ═══ Parameter - pszFileName ═══ pszFileName (PSZ) - input The fully qualified name of the project file to read information from. ═══ Parameter - pPrjInfo ═══ pPrjInfo (PWKFBASEPROJECT) - output Pointer to the base project information data structure in which to return the retrieved project information. ═══ Return Values - WkfReadProject ═══ (APIRET) - return values WkfReadProject returns the following values: NOERROR Project information successfully returned. Other An error occurred. ═══ Notes - WkfReadProject ═══ This WorkFrame/2-provided function reads project information from a base project file and returns an initialized PWKFBASEPROJECT structure. The information returned reflects that in the base project's Settings notebook. Before you can use this function, you will need to issue a WkfOpenProjectFile call to prepare the project file for reading. ═══ Example - WkfReadProject ═══ The following pseudo-code illustrates how this interface could be used: /* Open project file for reading */ pszPrjFilename = "C:\\DESKTOP\\PROJECTS\\MY PROJECT"; hProject = WkfOpenProjectFile ( NULLHANDLE, /* Just use desktop's anchor block handle */ pszPrjFilename, WKF_ACCESS_READ); /* Read project data info bpProject buffer */ WKFBASEPROJECT bpProject; if (hProject != NULLHANDLE) /* Project opened successfully */ rc = WkfReadProject ( pszPrjFilename, &bpProject ); else return; ═══ 14.3.3. WkfQueryProjectData ═══ WkfQueryProjectData Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryProjectData ═══ This WorkFrame/2*-provided function queries a base project file to retrieve tool-specific information stored using WkfWriteProjectData. #define INCL_WKFPRJ #include BOOL APIENTRY WkfQueryProjectData ( LHANDLE hProject, /* Project handle */ PSZ pszApp, /* Application key name */ PSZ pszKey, /* Data key name */ PVOID pBuffer, /* Pointer to buffer to contain returned value */ PULONG pulBufLen /* Size of the pBuffer field */ ); ═══ Parameter - hProject ═══ hProject (LHANDLE) - input The project handle returned from the WkfOpenProjectFile function. ═══ Parameter - pszApp ═══ pszApp (PSZ) - input Application key name of data to retrieve. The name must be specified in upper-case. See Using the Project APIs for more information on using key names to store and access data in project files. ═══ Parameter - pszKey ═══ pszKey (PSZ) - input Data key name of the data to retrieve. See Using the Project APIs for more information on using key names to store and access data in project files. ═══ Parameter - pBuffer ═══ pBuffer (PVOID) - input/output Pointer to a buffer to contain the return value. The buffer should be of a compatible type with the value to be returned. ═══ Parameter - pulBufLen ═══ pulBufLen (ULONG) - input/output Pointer to a ULONG field. On entry, this field should contain the maximum length, in bytes, of the buffer pointed to by pBuffer. On exit, this field contains the number of bytes returned. ═══ Return Values - WkfQueryProjectData ═══ (BOOL) - return values WkfQueryProjectData returns the following values: TRUE Data successfully returned. FALSE Unable to read requested data. ═══ Notes - WkfQueryProjectData ═══ This WorkFrame/2-provided function queries tool-specific project data from a base project file and returns the data in the pbuffer buffer. The information is retrieved using the key names specified by pszApp and pszKey. The requested data must have been previously stored using the WkfWriteProjectData interface. Before you can use this function, you will need to issue a WkfOpenProjectFile call to prepare the project file for reading. ═══ Example - WkfQueryProjectData ═══ The following pseudo-code illustrates how this interface could be used to retrieve previously-stored tool options from the project file: POPTIONS pOptions; PULONG pulBufLen; *pulBufLen = 2 * sizeof(OPTIONS) + OPTIONS_DATA_LENGTH; /* Open project file */ hProject = WkfOpenProjectFile ( NULLHANDLE, pszPrjFilename, WKF_ACCESS_READ); /* Now read options from project file */ WkfQueryProjectData ( hProject, "IBMTheTool", /* Application name key */ "TheToolOptions", /* Data name key */ (PVOID)&pOptions, /* Pointer to options buffer */ &pulBufLen); /* Pointer to length buffer */ /* Process options */ : /* Close the project file and release access */ WkfCloseProjectFile ( hProject ); free ( pOptions ); ═══ 14.3.4. WkfWriteProjectData ═══ WkfWriteProjectData Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfWriteProjectData ═══ This WorkFrame/2*-provided function write tool-specific data to a base project file. The stored information can be retrieved using using the WkfQueryProjectData interface. #define INCL_WKFPRJ #include BOOL APIENTRY WkfWriteProjectData ( LHANDLE hProject, /* Project handle */ PSZ pszApp, /* Application key name */ PSZ pszKey, /* Data key name */ PVOID pBuffer, /* Pointer to buffer containing data to store */ ULONG ulBufLen /* Size of the pBuffer field */ ); ═══ Parameter - hProject ═══ hProject (LHANDLE) - input The project handle returned from the WkfOpenProjectFile function. ═══ Parameter - pszApp ═══ pszApp (PSZ) - input Application key name of data to store. See Using the Project APIs for more information on using key names to store and access data in project files. ═══ Parameter - pszKey ═══ pszKey (PSZ) - input Data key name of the data to store. If this parameter is NULL, all the data associated with the application key specified in pszApp is deleted. See Using the Project APIs for more information on using key names to store and access data in project files. ═══ Parameter - pBuffer ═══ pBuffer (PVOID) - input Pointer to the buffer containing the data to store. If this parameter is NULL, the data associated with the data key specified in pszKey is deleted. ═══ Parameter - ulBufLen ═══ ulBufLen (ULONG) - input The length, in bytes, of the input buffer pointed to by pBuffer. ═══ Return Values - WkfWriteProjectData ═══ (BOOL) - return values WkfWriteProjectData returns the following values: TRUE Data written successfully. FALSE Unable to write data. ═══ Notes - WkfWriteProjectData ═══ This WorkFrame/2-provided function writes tool-specific project data to a base project file. This function is particularly useful for storing tool options for the project. The information is written using the key names specified by pszApp and pszKey and retrieved with the same keys. The stored data can be retrieved using the WkfQueryProjectData interface. Before you can use this function, you will need to issue a WkfOpenProjectFile call to prepare the project file for writing. ═══ Example - WkfWriteProjectData ═══ The following pseudo-code illustrates how this interface could be used to store tool options for the project: /* Store tool options for the project */ typedef struct _OPTIONS /* Structure to hold options data */ { ULONG cb; BOOL fPrompt; PSZ pszCommandLine; PSZ pszErrTemplate; CHAR szData[1]; } OPTIONS, *POPTIONS; size = 2 * sizeof(OPTIONS) + OPTIONS_DATA_LENGTH; POPTIONS pOptions; pOptions = calloc ( 1, size); /* Initialize OPTIONS structure */ pOptions->cb = size; pOptions->fPrompt = FALSE; strcpy( pOptions->pszCommandLine, SOME_CMD_LINE ); strcpy( pOptions->pszErrTemplate, SOME_ERR_TEMPLATE ); strcpy( pOptions->szData, SOME_DATA ); /* Open project file */ hProject = WkfOpenProjectFile ( NULLHANDLE, pszPrjFilename, WKF_ACCESS_ALL | WKF_SHARE_DENYWRITE ); /* Now write options to project file */ WkfWriteProjectData ( hProject, /* Project handle */ "IBMTheTool", /* Application name key */ "TheToolOptions", /* Data name key */ (PVOID)pOptions, /* Pointer to buffer */ pOptions->cb)); /* Buffer length */ free ( pOptions ); /* Close the project file and release access */ WkfCloseProjectFile ( hProject ); ═══ 14.3.5. WkfCloseProjectFile ═══ WkfCloseProjectFile Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfCloseProjectFile ═══ This WorkFrame/2*-provided function closes an open base project file. #define INCL_WKFPRJ #include BOOL APIENTRY WkfCloseProjectFile ( LHANDLE hProject /* Project handle */ ); ═══ Parameter - hProject ═══ hProject (LHANDLE) - input The project handle returned from the WkfOpenProjectFile function. ═══ Return Values - WkfCloseProjectFile ═══ (BOOL) - return values WkfCloseProjectFile returns the following values: TRUE File closed successfully. FALSE Unable to close file. ═══ Notes - WkfCloseProjectFile ═══ This WorkFrame/2-provided function closes the base project file opened with the WkfOpenProjectFile interface. Call this interface when you are finished querying the project file. ═══ Example - WkfCloseProjectFile ═══ The following pseudo-code illustrates how this interface could be used: /* Finished with project file */ WkfCloseProjectFile ( hProject ); ═══ 15. Actions Profiles ═══ This section describes the WorkFrame/2*-provided APIs that can be used to obtain information about actions profiles. ═══ 15.1. Using the Actions Profile APIs ═══ The Actions Profile API's provide a way to list the actions, environment variables, and types, that are defined in a given actions profile. The actions profile APIs query a given actions profile and the Default Actions Profile (DAP) to return an initialized structure with the requested information. For example, WkfQueryActions returns a pointer to a WKF_ACTIONS structure that contains a list of WKF_ACTION structures that describe each action. Similarly, WkfQueryEnvirons returns a pointer to an initialized WKF_ENVIRONS list of WKF_ENVIRON structures that describe each environment variable. After calling an actions profile API, you must free the returned structure or list of structures using the appropriate WkfFree... API. Actions profile desktop objects are created and set using the OS/2* APIs, WinCreateObject and WinSetObjectData. This is discussed in Managing Actions Profiles. ═══ 15.2. Managing Actions Profiles ═══ This section discusses the use of the OS/2 APIs, WinCreateObjectData, WinSetObjectData, and WinDestroyObject to create and delete WorkFrame/2* actions profile desktop objects. Note: Any operations performed on WorkFrame/2* objects (such as projects and actions profiles) that are not accomplished using the WorkFrame/2 integration APIs, are not guaranteed to be compatible in future versions of WorkFrame/2. APIs to set, create, and delete actions profiles will be made available in future versions. See the Copyright Notice for more information. ═══ 15.2.1. Creating Actions Profiles ═══ To create an actions profile object, call WinCreateObject specifying "DDE3Profile" for the object's SOM class, and the correct keyname-value pairs in the setup string. Following is an example of how to create an actions profile: hProfile = WinCreateObject ( "DDE3Profile", /* Actions profile class name */ "Sample Actions Profile", /* Actions profile title */ pszSetupString, /* Setup string */ "C:\\Desktop\\My Profiles", /* Create object in this folder */ CO_REPLACEIFEXISTS); /* Creation flags */ The above call to WinCreateObject creates an actions profile with the title "Sample Actions Profile", in a folder on the Desktop called "My Profiles". The creation flag indicates that the actions profile should be replaced if it already exists. The profile's object handle is returned. If you wanted to create an actions profile in the WorkFrame/2 Actions Profiles folder, you could have specified its persistent object ID in the fourth parameter of WinCreateObject See Persistent Object IDs for a list of WorkFrame/2 object IDs. The required setup string consists of a series of keyname-value pairs, defined for the class, that initialize the object. Keynames are separated by semicolons, and values are separated by commas, as in: "key=value; key2=value1,value2;" For example, an actions profile setup string could look like this (note that the caret "^" must precede semi-colons and commas that that are to be interpreted as literals in the setup string): pszInclude = "C:\\INCLUDES^;%INCLUDE%" j = sprintf (pszSetupString, WKF_ENVIRON_KEY"=INCLUDE,%s", pszInclude); fSuccess = WinSetObjectData (hProject, /* Project handle from WinCreateObject */ pszSetupString); /* Setup string */ The following table shows the keyname-value pairs supported by the "DDE3Profile" class: ┌─────────────────────────┬───────────────────────────────────┬────────────────────────────────────────┐ │Keyname (string constant)│Value │Description │ ├─────────────────────────┼───────────────────────────────────┼────────────────────────────────────────┤ │WKF_ACTION_KEY │See WKF_ACTION_KEY values │This adds an action to the actions │ │ │ │profile. │ ├─────────────────────────┼───────────────────────────────────┼────────────────────────────────────────┤ │WKF_IFFOUND_KEY │Program name, for example "epm.exe"│When followed by a WKF_ACTION_KEY │ │ │ │keyword, it is interpreted to mean that │ │ │ │if the program name is found along the │ │ │ │current path, then the action should be │ │ │ │added according to the immediately │ │ │ │following WKF_ACTION_KEY keyname-value │ │ │ │pair. │ │ │ │Note that this keyword must always be │ │ │ │followed by WKF_ACTION_KEY. │ ├─────────────────────────┼───────────────────────────────────┼────────────────────────────────────────┤ │WKF_ENVIRON_KEY │, │This adds an environment variable to the│ │ │for example │actions profile, and is equivalent to │ │ │"INCLUDE,C:\\PRJ\\HEADERS^;%I│setting environment variable values on │ │ │ │the Environments page of the actions │ │ │ │profile's Settings notebook. │ └─────────────────────────┴───────────────────────────────────┴────────────────────────────────────────┘ Notes 1. All keynames, except the Action name and Program name values of the WKF_ACTION_KEY fields, have safe default values, so it is never required to include all the possible keyname-value pairs in the setup string. Specify a NULL setup string to use the default values. 2. You can only add or change one action and one environment variable per call to WinSetObjectData. 3. Since the "DDE3Profile" class is subclassed from the "WPFileSystem" Workplace Shell class, keyname=values pairs defined for "WPFileSystem" are also valid for "DDE3Profile". See the online PM Reference from IBM* Developer's Toolkit for more information on Workplace Shell classes and the WinCreateObject API. ═══ WKF_ACTION_KEY Values ═══ The WKF_ACTION_KEY contains the following value fields which correspond to fields in an action's Change action or Add action notebook. The value fields must be enumerated in the order that they are given here. With the exception of the rightmost fields, fields that are to contain the default value must be specified with a blank and delimited by a comma. All the following value fields, except for Action name and Program name, have safe default values, so it is not required to specify all the possible value fields for WKF_ACTION_KEY. Action name Name of the action, for example, "IBM C Set ++" . This value must be specified. Action class The action's class name, for example, "COMPILE" . Program name Name of the action's executable, for example, "icc.exe" . This value must be specified. Source type Source file masks and predefined named types, each separated by a newline (\n) character. For example, "*.c\n*.cpp\nCSOURCE\nCPPSOURCE" . Target type Target file masks and predefined named types, each separated by a newline (\n) character. For example, "*.obj\n*.exe\n*.dll\nMAPFILES" . Options DLL name The unqualified name of the options DLL for the action, for example, "DDE3DEF2" . Options DLL entrypoint Name of the entrypoint in the options DLL that contains the action integration support function. For example, "COMPILE" . Action type Currently, WKF_ACTIONTYPE_CMD is the only action type supported. Actions scope The scope of the action, one of: WKF_ACTIONSCOPE_PROJECT (applies to projects only), WKF_ACTIONSCOPE_FILE (applies to files only), or WKF_ACTIONSCOPE_BOTH (can apply to both files and projects). Menu options The kind of menu the action is to appear on, one of: WKF_MENUSCOPE_DETAIL (action is shown only if the extended menu option is selected for the project), or WKF_MENUSCOPE_SHORT (action appears on all menus). Run mode Session the action should be started in, one of: WKF_RUNMODE_FULLSCREEN (action is to be started in a full-screen session), WKF_RUNMODE_WINDOW (action is to be started in an AVIO window), or WKF_RUNMODE_MONITOR (action should be run in a WorkFrame/2* Monitor window). Help command Command that displays any customized help for the action, for example "VIEW ToolHelp" or "VIEW %TOPIC% ". Help topic If the help topic was specified with the substitution variable %TOPIC% in the previous field, you can specify the help topic here, for example "ToolHelp" . For example: pszAction = "IBM C Set ++,COMPILE,icc.exe,*.cpp,*.obj,DDE4ICC2,COMPILE, \ WKF_ACTIONTYPE_CMD,WKF_ACTIONSCOPE_FILE,WKF_MENUSCOPE_SHORT, \ WKF_RUNMODE_MONITOR"; j = sprintf (pszSetupString, WKF_ACTION_KEY"=%s", pszAction); ═══ 15.2.2. Setting Actions Profiles Data ═══ Set actions profile data by invoking the WinSetObjectData OS/2* API with the actions profile handle returned by WinCreateObject when the object was created. WinSetObjectData expects a setup string containing the keyword-value pairs that you want to change. Use WinQueryObject to obtain the name of any actions profile you want to change. Adding an Action For example, to add an action to the Default Actions Profile (DAP), you might issue these function calls: /* Get DAP's object handle */ hDAP = WinQueryObject (); /* Build setup string */ pszIfFound = "iconedit.exe"; pszAction = "Icon Edit,EDIT,iconedit.exe,*.ico,,DDE3DEF2,DEFAULT,WKF_ACTIONTYPE_CMD,WKF_ACTIONSCOPE_FILE, \ WKF_MENUSCOPE_SHORT,WKF_RUNMODE_DEFAULT,view toolinfo %TOPIC%,Icon Editor"; j = sprintf (pszSetupString, WKF_IFFOUND_KEY"=%s;"WKF_ACTION_KEY"=%s", pszIfFound, pszAction); /* Add action */ fSuccess = WinSetObjectData ( hDAP, /* DAP object handle */ pszSetupString); /* Setup string */ Changing an Action To change the settings for an existing action, you must specify all the value fields of the WKF_ACTION_KEY keyword in the setup string. A WKF_ACTION_KEY value is interpreted as a replacement of the existing action. Specifying a blank value for a field will delete the previous value of the field. For example, to change the options DLL for the action added in the example shown above from DDE3DEF2.DLL to IEDITOPT.DLL, do the following: /* Build setup string */ pszAction = Icon Edit,EDIT,iconedit.exe,*.ico,,IEDITOPT,ICONEDIT,WKF_ACTIONTYPE_CMD, \ WKF_ACTIONSCOPE_FILE,WKF_MENUSCOPE_SHORT,WKF_RUNMODE_DEFAULT, \ view toolinfo %TOPIC%,Icon Editor"; j = sprintf (pszSetupString, WKF_ACTION_KEY"=%s", pszAction); /* Change action */ fSuccess = WinSetObjectData ( hDAP, /* DAP object handle */ pszSetupString); /* Setup string */ Deleting an Action To delete an action, specify only the class name and action name with blanks for the rest of the WKF_ACTION_KEY fields in the setup string. For example, /* Build setup string */ pszAction = "WKF_ACTION_KEY=Icon Edit, EDIT, , , , , , , , , , , "; j = sprintf (pszSetupString, WKF_ACTION_KEY"=%s", pszAction); /* Delete action */ fSuccess = WinSetObjectData ( hAP, /* Actions profile's object handle */ pszSetupString); /* Setup string */ Querying Actions Profiles Actions profiles can be queried using the WorkFrame/2*-provided actions profiles APIs. See the online PM Reference from IBM* Developer's Toolkit for more information on OS/2 APIs and Workplace Shell methods. ═══ 15.2.3. Deleting Actions Profiles ═══ Actions profiles can be permanently deleted using the OS/2* WinDestroyObject API. For example: fSuccess = WinDestroyObject (hProfile); /* Actions profile object handle */ See the online PM Reference from IBM* Developer's Toolkit for more information on the WinDestroyObject API. ═══ 15.3. Actions Profile APIs ═══ This section descibes the WorkFrame/2*-provided APIs for obtaining information about an actions profile. The function prototypes and constant declarations for the actions profile APIs are in the WKFPRF.H C header file. ═══ 15.3.1. WkfQueryActionList ═══ WkfQueryActionList Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryActionList ═══ This WorkFrame/2*-provided function returns the list of actions present in the specified actions profile and the Default Actions Profile. #define INCL_WKFPRF #include APIRET APIENTRY WkfQueryActionList ( PSZ pszPrfFileName, /* File name of the actions profile */ PWKF_ACTIONS *ppwkfActions /* List of actions - returned */ ); ═══ Parameter - pszPrfFilename ═══ pszPrfFilename (PSZ) - input The fully qualified ASCIIZ file name of the actions profile whose actions to query along with those in the Default Actions Profile If this field is NULL, then the actions are queried from the Default Actions Profile only. ═══ Parameter - *ppwkfActions ═══ *ppwkfActions (PWKF_ACTIONS) - input/output On entry, this field should contain the address that contains the pointer to the PWKF_ACTIONS return structure. On exit, this field is updated with one of the following values: 1. A pointer to the WKF_ACTIONS structure containing the list of actions 2. A pointer to the WKF_ACTIONS structure containing a NULL list of actions and a ulCount field set to zero, if there are no actions in the Default Actions Profile, and the actions profile specified by pszPrfFilename 3. A NULL pointer, if there were errors reading one or both profiles. ═══ Return Values - WkfQueryActionList ═══ (APIRET) - return values WkfQueryActionList returns the following values in addition to standard OS/2* return codes: NO_ERROR No errors occurred. The list of actions from the specified actions profile and the Default Actions Profile is returned. WKF_INVALID_PROFILES Both the specified actions profile and Default Actions Profile were invalid. No list is returned. WKF_PROFILES_NOT_FOUND Both the specified actions profile and Default Actions Profile were not found. No list is returned. WKF_DFLTPROFILE_NOTFOUND Default Actions Profile was not found. If the specified actions profile was found and was valid, then the list of actions in that profile is returned. WKF_INVALID_ACTIONSPROFILE The specified actions profile was invalid. If the Default Actions Profile was valid, then the list of actions from that profile is returned. WKF_ACTIONSPROFILE_NOTFOUND The specified actions profile was not found. If the Default Actions Profile was found and was valid, then the list of actions from that profile is returned. ═══ Notes - WkfQueryActionList ═══ This WorkFrame/2*-provided function queries the list of actions from the actions profile identified by the pszPrfFilename field. It also appends the actions from the Default Actions Profile (DAP). If there are duplicate actions defined in the actions profile and the DAP, the action found in the DAP is discarded. Actions are returned sorted by class name. To obtain the list of actions only from the DAP, specify NULL for the pszPrfFileName field. After calling this function, you must call WkfFreeActions to free the returned *ppfwkfActions list if it is not NULL on exit. Note that some error return codes may result in a partially filled action list. If there were errors reading either profile, then *ppwkfActions is set to NULL. Check for a NULL *ppwkfActions value before using it. ═══ Example - WkfQueryActionList ═══ The following pseudo-code illustrates how this interface might be used: /* Query the list of actions in the CLC Sample Actions Profile */ PSZ pszType = "*.c"; PSZ pszProfile = "C:\\Desktop\\IBM WorkFrame!2 V2.1\\CLC Actions Profile"; PWKF_ACTIONS actions; int i, ulActCount; if (NO_ERROR == WkfQueryActionList (pszProfile, &actions)) { /* Process returned list of actions */ if ( (ulActCount = actions->ulCount) > 0) for (i=0; iapActions[i]->pszActionName, actions->apActions[i]->pszActionClass, actions->apActions[i]->pszCommand, actions->apActions[i]->pszSrcMask, actions->apActions[i]->pszTgtMask, actions->apActions[i]->pszDllName, actions->apActions[i]->pszDllEntryName, actions->apActions[i]->ucActionType, actions->apActions[i]->ucRunMode, actions->apActions[i]->pszHelpCmd, : ); } WkfFreeActions(actions); ═══ 15.3.2. WkfQueryActions ═══ WkfQueryActions Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryActions ═══ This WorkFrame/2*-provided function returns the list of actions in the specified actions profile and the Default Actions Profile, that apply to the specified object type. #define INCL_WKFPRF #include APIRET APIENTRY WkfQueryActions ( PSZ pszPrfFileName, /* File name of the actions profile */ PSZ pszObjectType, /* Object types to which the returned actions can be applied */ PWKF_ACTIONS *ppwkfActions /* List of actions - returned */ ); ═══ Parameter - pszPrfFilename ═══ pszPrfFilename (PSZ) - input The fully qualified file name of the actions profile whose actions to query along with those in the Default Actions Profile. If this field is NULL, then the actions are queried from the Default Actions Profile only. ═══ Parameter - pszObjectType ═══ pszObjectType (PSZ) - input If this field is NULL, all the actions from the Default Actions Profile and the profile identified by the pszPrfFilename field are returned. Otherwise, only the actions matching the object type (or mask) specified in this field are returned. ═══ Parameter - *ppwkfActions ═══ *ppwkfActions (PWKF_ACTIONS) - input/output On entry, this field should contain the address that contains the pointer to the PWKF_ACTIONS return structure. On exit, this field is updated with one of the following values: 1. A pointer to the WKF_ACTIONS structure containing the list of actions 2. A pointer to the WKF_ACTIONS structure containing a NULL list of actions and a ulCount field set to zero, if there are no actions in either profile that apply to the type specified by pszObjectType 3. A NULL pointer, if there were errors. ═══ Return Values - WkfQueryActions ═══ (APIRET) - return values WkfQueryActions returns the following values in addition to standard OS/2* return codes: NO_ERROR No errors occurred. The list of actions from the specified actions profile and the Default Actions Profile is returned. WKF_UNRESOLVED_TYPE The specified file mask could not be resolved by the OS/2 system. If the specified object type is not a valid WorkFrame/2* type, then it is assumed to be a file mask. WKF_INVALID_PROFILES Both the specified actions profile and Default Actions Profile were invalid. No list is returned. WKF_PROFILES_NOT_FOUND Both the specified actions profile and Default Actions Profile were not found. No list is returned. WKF_DFLTPROFILE_NOTFOUND Default Actions Profile was not found. If the specified actions profile was found and was valid, then the list of actions in that profile is returned. WKF_INVALID_ACTIONSPROFILE The specified actions profile was invalid. If the Default Actions Profile was valid, then the list of actions from that profile is returned. WKF_ACTIONSPROFILE_NOTFOUND The specified actions profile was not found. If the Default Actions Profile was found and was valid, then the list of actions from that profile is returned. ═══ Notes - WkfQueryActions ═══ This WorkFrame/2*-provided function queries the list of actions from the pszPrfFilename actions profile, and the Default Actions Profile, that can be applied to the object type given in the pszObjectType field. If the specified object type is not a valid WorkFrame/2* type, then it is assumed to be a file mask. If there are duplicate actions defined in the actions profile and the DAP, the action found in the DAP is discarded. Actions are returned sorted by class name. To obtain the list of actions only from the DAP, specify NULL for the pszPrfFileName field. After calling this function, you must call WkfFreeActions to free the returned *ppfwkfActions list if it is not NULL on exit. Note that some error return codes may result in a partially filled action list. If there were errors reading either profile or resolving the specified type, then *ppwkfActions is set to NULL. Check for a NULL *ppwkfActions value before using it. ═══ Example - WkfQueryActions ═══ The following pseudo-code illustrates how this interface might be used: /* Query the list of actions in the C/C++ Tools Actions Profile that */ /* apply to C files */ PSZ pszType = "*.c"; PSZ pszProfile = "C:\\Desktop\\IBM C!C++ Tools 2.01\\IBM C!C++ Tools^Actions Profile"; PWKF_ACTIONS actions; int i, ulActCount; if (NO_ERROR == WkfQueryActions (pszProfile, pszType, &actions)) { /* Process returned list of actions */ if ( (ulActCount = actions->ulCount) > 0) for (i=0; iapActions[i]->pszActionName, actions->apActions[i]->pszActionClass, actions->apActions[i]->pszCommand, actions->apActions[i]->pszSrcMask, actions->apActions[i]->pszTgtMask, actions->apActions[i]->pszDllName, actions->apActions[i]->pszDllEntryName, actions->apActions[i]->ucActionType, actions->apActions[i]->ucRunMode, actions->apActions[i]->pszHelpCmd, : ); } : } WkfFreeActions(actions); ═══ 15.3.3. WkfFreeActions ═══ WkfFreeActions Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfFreeActions ═══ This WorkFrame/2*-provided function frees the list of actions returned by WkfQueryActionList and WkfQueryActions. #define INCL_WKFPRF #include VOID APIENTRY WkfFreeActions ( PWKF_ACTIONS *ppwkfActions /* Pointer to action list structure to free */ ); ═══ Parameter - *ppwkfActions ═══ *ppwkfAction (PWKF_ACTIONS) - input This function frees the memory allocated to this pointer. This is the pointer to the PWKF_ACTIONS structure returned by WkfQueryActionList and WkfQueryActions. ═══ Return Values - WkfFreeActions ═══ (VOID) - return values WkfFreeActions has no return values. ═══ Notes - WkfFreeActions ═══ This WorkFrame/2*-provided function frees the memory allocated by WkfQueryActionList and WkfQueryActions to hold the returned list of actions. ═══ Example - WkfFreeActions ═══ The following pseudo-code illustrates how this interface might be used: PSZ pszType = "*.c"; PSZ pszProfile = "C:\\Desktop\\IBM C!C++ Tools 2.01\\IBM C!C++ Tools^Actions Profile"; PWKF_ACTIONS actions; int i, ulActCount; if (NO_ERROR == WkfQueryActions (pszFilename, pszType, &actions)) { /* Process returned list of actions */ if ( (ulActCount = actions->ulCount) > 0) for (i=0; iapActions[i]->pszActionName, actions->apActions[i]->pszActionClass, actions->apActions[i]->pszCommand, actions->apActions[i]->pszSrcMask, actions->apActions[i]->pszTgtMask, actions->apActions[i]->pszDllName, actions->apActions[i]->pszDllEntryName, actions->apActions[i]->ucActionType, actions->apActions[i]->ucRunMode, actions->apActions[i]->pszHelpCmd, : ); } : } /* Finished with list of actions */ WkfFreeActions(actions); ═══ 15.3.4. WkfQueryEnvirons ═══ WkfQueryEnvirons Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryEnvirons ═══ This WorkFrame/2*-provided function returns the list of environment variables, and their values, from the specified actions profile and the Default Actions Profile. #define INCL_WKFPRF #include APIRET APIENTRY WkfQueryEnvirons ( PSZ pszPrfFileName, /* Actions profile file name */ PWKF_ENVIRONS *ppwkfEnvirons /* List of environments - returned */ ); ═══ Parameter - pszPrfFilename ═══ pszPrfFilename (PSZ) - input The fully-qualified ASCIIZ file name of the actions profile whose environments to query along with those in the Default Actions Profile. If this field is NULL, then the environments are queried from the Default Actions Profile only. ═══ Parameter - *ppwkfEnvirons ═══ *ppwkfEnvirons (PWKF_ENVIRONS) - input/output On entry, this field should contain the address to contain the pointer to the PWKF_ENVIRONS return structure. On exit, this field is updated with the pointer to the WKF_ENVIRONS structure containing the list of environments. ═══ Return Values - WkfQueryEnvirons ═══ (APIRET) - return values WkfQueryEnvirons returns the following values in addition to standard OS/2* return codes: NO_ERROR No errors occurred. The list of environs from the specified actions profile and the Default Actions Profile is returned. WKF_INVALID_PROFILES Both the specified actions profile and Default Actions Profile were invalid. No list is returned. WKF_PROFILES_NOT_FOUND Both the specified actions profile and Default Actions Profile were not found. No list is returned. WKF_DFLTPROFILE_NOTFOUND Default Actions Profile was not found. If the specified actions profile was found and was valid, then the list of environments from that profile is returned. WKF_INVALID_ACTIONSPROFILE The specified actions profile was invalid. If the Default Actions Profile was valid, then the list of environments from that profile is returned. WKF_ACTIONSPROFILE_NOTFOUND The specified actions profile was not found. If the Default Actions Profile was found and was valid, then the list of environments from that profile is returned. ═══ Notes - WkfQueryEnvirons ═══ This WorkFrame/2*-provided function queries the merged list of environment variables from the pszPrfFilename actions profile, and the Default Actions Profile. If there are duplicate environment variables defined in the actions profile and the DAP, the environment variable found in the DAP is discarded. To obtain the list of environment variables only from the DAP, specify NULL for the pszPrfFileName field. After calling this function, you must call WkfFreeEnvirons to free the returned *ppfwkfEnvirons list if it is not NULL on exit. Note that some error return codes may result in a partially filled environments list. If no environments are present in either profile, then *ppwkfEnvirons is set to NULL even if NO_ERROR is returned. Check for a NULL *ppwkfEnvirons value before using it. ═══ Example - WkfQueryEnvirons ═══ The following pseudo-code illustrates how this interface might be used: PWKF_ENVIRONS Environs; int ulEnvCount; int i; if (NO_ERROR == WkfQueryEnvirons("C:\\DESKTOP\\MY ACTIONS PROFILE", &Environs)) { /* Process returned list of environment variables */ if ( (ulEnvCount = Environs->ulCount) > 0) for (i=0; iapEnvirons[i]->pszEnvName, Environs->apEnvirons[i]->pszEnvStr); : } : } /* endif */ : /* Finished working with Environs pointer */ WkfFreeEnvirons(Environs); ═══ 15.3.5. WkfFreeEnvirons ═══ WkfFreeEnvirons Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfFreeEnvirons ═══ This WorkFrame/2*-provided function frees the list of environments returned by WkfQueryEnvirons. #define INCL_WKFPRF #include VOID APIENTRY WkfFreeEnvirons ( PWKF_ENVIRONS *ppwkfEnvirons /* Pointer to environments list structure to free */ ); ═══ Parameter - *ppwkfEnvirons ═══ *ppwkfEnvirons (PWKF_ENVIRONS) - input A pointer to the PWKF_ENVIRONS structure returned by WkfQueryEnvirons. The memory allocated to this pointer will be freed. ═══ Return Values - WkfFreeEnvirons ═══ (VOID) - return values WkfFreeEnvirons has no return values. ═══ Notes - WkfFreeEnvirons ═══ This WorkFrame/2*-provided function frees the memory allocated by the WkfQueryEnvirons function to hold the returned list of environments. ═══ Example - WkfFreeEnvirons ═══ The following pseudo-code illustrates how this interface might be used: PWKF_ENVIRONS Environs; int ulEnvCount; int i; if (NO_ERROR == WkfQueryEnvirons("C:\\DESKTOP\\MY ACTIONS PROFILE", &Environs)) { /* Process returned list of environment variables */ if ( (ulEnvCount = Environs->ulCount) > 0) for (i=0; iapEnvirons[i]->pszEnvName, Environs->apEnvirons[i]->pszEnvStr); : } : } /* endif */ : /* Finished working with Environs pointer */ WkfFreeEnvirons(Environs); ═══ 15.3.6. WkfQueryTypes ═══ WkfQueryTypes Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryTypes ═══ This WorkFrame/2*-provided function returns the list of defined WorkFrame/2 types. #define INCL_WKFPRF #include APIRET APIENTRY WkfQueryTypes ( ULONG ulSearchType, /* Pattern or user-defined */ PWKF_TYPES *ppwkfTypes /* List of types - returned */ ); ═══ Parameter - ulSearchType ═══ ulSearchType (ULONG) - input This field can contain one of the following values: 1 WKF_TYPE_PATTERN Currently, this is the only supported search type. 2 WKF_TYPE_USERDEFINE Currently not supported. ═══ Parameter - *ppwkfTypes ═══ *ppwkfTypes (PWKF_TYPES) - input/output On entry, this field should contain the address to contain the pointer to the PWKF_TYPES return structure. On exit, this field is updated with the pointer to the WKF_TYPES structure containing the list of WorkFrame/2*-defined types. WorkFrame/2 types are defined on the Types page of the Default Actions Profile. ═══ Return Values - WkfQueryTypes ═══ (APIRET) - return values WkfQueryTypes returns the following values in addition to standard OS/2* return codes: NO_ERROR No errors occurred. The list of WorkFrame/2* types is returned. WKF_DFLTPROFILE_NOTFOUND Default Actions Profile was not found. No list is returned. ═══ Notes - WkfQueryTypes ═══ This WorkFrame/2*-provided function queries the list of WorkFrame/2 types defined in the Default Actions Profile. After calling this function, you must call WkfFreeTypes to free the returned *ppwkfTypes list if it is not NULL on exit. If no WorkFrame/2 types have been defined, then *ppwkfTypes is set to NULL even if NO_ERROR is returned. Check for a NULL *ppwkfTypes value before using it. ═══ Example - WkfQueryTypes ═══ The following pseudo-code illustrates how this interface might be used: PWKF_TYPES Types; int ulTypCount; int i; if (NO_ERROR == WkfQueryTypes(WKF_TYPE_PATTERN, &Types)) { /* Process returned list of types */ if ( (ulTypCount = Types->ulCount) > 0) for (i=0; iapTypes[i]->pszTypeName, Types->apTypes[i]->pszData); : } : } /* endif */ : /* Finished working with Types pointer */ WkfFreeTypes(Types); ═══ 15.3.7. WkfFreeTypes ═══ WkfFreeTypes Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfFreeTypes ═══ This WorkFrame/2*-provided function frees the list of environments returned by WkfQueryEnvirons. #define INCL_WKFPRF #include VOID APIENTRY WkfFreeTypes ( PWKF_TYPES pwkfTypes /* Pointer to types list structure to free */ ); ═══ Parameter - pwkfTypes ═══ pwkfTypes (PWKF_TYPES) - input A pointer to the PWKF_TYPES structure returned by WkfQueryTypes. The memory allocated to this pointer will be freed. ═══ Return Values - WkfFreeTypes ═══ (VOID) - return values WkfFreeTypes has no return values. ═══ Notes - WkfFreeTypes ═══ This WorkFrame/2*-provided function frees the memory allocated by the WkfQueryTypes function to hold the returned list of WorkFrame/2 types. ═══ Example - WkfFreeTypes ═══ The following pseudo-code illustrates how this interface might be used: PWKF_TYPES Types; int ulTypCount; int i; if (NO_ERROR == WkfQueryTypes(WKF_TYPE_PATTERN, &Types)) { /* Process returned list of types */ if ( (ulTypCount = Types->ulCount) > 0) for (i=0; iapTypes[i]->pszTypeName, Types->apTypes[i]->pszData); : } : } /* endif */ : /* Finished working with Types pointer */ WkfFreeTypes(Types); ═══ 16. Router ═══ This section describes the messages and APIs that integrated tools can use to interact with the WorkFrame/2* router. ═══ 16.1. Using the Router APIs ═══ The router integrates any kind of tool that OS/2* supports, including OS/2 tools that run under: o VIO o Presentation Manager* o Workplace Shell* Clients register for communication with the WorkFrame/2* router using the WkfInitialize API. Typically, a client registers with the router when it opens, and terminates communication (using WkfTerminate) before it closes. Clients use the WkfNotify API to send messages to the router. WkfInitialize returns a router handle that is used to identify the routing session. The client must keep track of this handle to send messages and terminate the routing session. Each router message has an associated message information structure that is passed long with it. When a client sends a message, it must first allocate space for the appropriate structure using WkfAllocMsgData, initialize the allocated structure, and then send it using WkfNotify. Most of the router messages (described in this section) are information messages that are meant for broadcast to clients. Others, particularly WKFM_EXECUTEACTION, WKFM_LOGMESSAGE, and WKFM_LOGERROR, are explicit command messages that the router passes on to other clients for execution. For example, the router passes a WKFM_LOGMESSAGE message on to the Action Log to display a message on behalf of the sender. ═══ 16.1.1. Receiving Router Messages ═══ Clients receive messages from the router in one of three ways, depending on the communication mode specified at initialization: Presentation Manager* (PM) message queues This is the recommended procedure for PM programs. The router posts the message on the queue, with an initialized PWKF_SENDERINFO structure in MP1, and a corresponding initialized message information structure in MP2. Note for PM Applications: The WorkFrame/2 router reserves all message IDs from WM_USER to WM_USER+19, inclusive. Do not use any message IDs within this range to avoid conflicts with router IDs. SOM methods Workplace Shell*-integrated programs should use this communication mode. The SOM object should define a WkfReceiveMsg method to receive router messages. Named message pipes Note: This mode of router communication has not yet been implemented, however, it will be implemented in the near future as documented here. If you have an immediate need to integrate a non-PM program with WorkFrame/2*, please send a note to the workframe@vnet.ibm.com via the Internet. This is the recommended communication mode for non-PM programs. The router writes a message to the pipe in the following format: ┌────────────────────┬────────────────────────────────────────┐ │ Type │ Description │ ├────────────────────┼────────────────────────────────────────┤ │ULONG │Size of the message block (standard for │ │ │named message pipes) │ ├────────────────────┼────────────────────────────────────────┤ │ULONG │Message ID of router message being sent │ ├────────────────────┼────────────────────────────────────────┤ │WKF_SENDERINFO │Sender information structure │ ├────────────────────┼────────────────────────────────────────┤ │Message information │Structure type depends on message being │ │structure │sent │ └────────────────────┴────────────────────────────────────────┘ The pipe must be a named message pipe with duplex access mode, and an instance count of one. Clients receiving messages through named pipes should check for the ERROR_MORE_DATA return code from the DosRead OS/2* API in case the read buffer was not large enough to hold the entire message block. ═══ 16.1.2. Message Information Structures ═══ Every router message is sent with a corresponding information structure that contains data about the message. The first field in every message structure is a ULONG indicating the size of the structure. Following is a table showing the router messages and the names of their corresponding data structure typedefs: ┌─────────────────────────┬──────────────────────┐ │Router Message ID │Data Structure │ ├─────────────────────────┼──────────────────────┤ │WKFM_ACTIONEND │WKF_ACTIONENDINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_ACTIONSTART │WKF_ACTIONSTARTINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_APPSTARTNOTIFY │WKF_APPSTARTINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_APPTERMNOTIFY │WKF_APPTERMINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_CLIENTCHANGED │WKF_CHANGEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_CLIENTDELETED │WKF_DELETEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_CLIENTMOVED │WKF_MOVEINFO (added) │ ├─────────────────────────┼──────────────────────┤ │WKFM_CLIENTRENAMED │WKF_RENAMEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_EXECUTEACTION │WKF_EXECUTEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_FILECHANGED │WKF_FILECHANGEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_FILEDELETED │WKF_FILEDELETEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_FILERENAMED │WKF_FILERENAMEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_INITIALIZE │WKF_INITIALIZEINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_LOGERROR │WKF_ERRORMSGINFO │ ├─────────────────────────┼──────────────────────┤ │WKFM_LOGMESSAGE │WKF_LOGMSGINFO │ └─────────────────────────┴──────────────────────┘ ═══ 16.1.3. Using the Message Data Structures ═══ Each router message sent is accompanied by a corresponding information structure (see Message Information Structures) that could be allocated in shared memory. When a client receives a router message, it should first issue a WkfAccessMsgData call to obtain permission before accessing the information structure. To send a message to the router, a client should first allocate memory for the corresponding information structure using WkfAllocMsgData. Many of the router information structures contain a CHAR array with a single element that is declared at the end of the structure. For example, notice the szParm[1] member in the following structure: typedef struct _WKF_RENAMEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flChanged; /* Reserved */ CHAR szParm[1]; /* Name of file renamed */ } WKF_RENAMEINFO; Such members are conceptualized as dynamically-sized null-terminated strings that should be explicitly allocated before they are initialized. When allocating memory for the information structure using WkfAllocMsgData, specify enough space for the structure, plus an additional amount for the last string member. The rest of the string can be accessed via the first element of the array since the elements are stored contiguously in memory. Initialize and copy such strings using the strcpy() C library function. ═══ 16.2. Router APIs ═══ This section descibes: 1. WorkFrame/2*-supplied functions for registering and deregistering from the WorkFrame/2 router, and sending and receiving router messages 2. WorkFrame/2-defined messages used within the message routing facilities. The function prototypes and message definitions for the router APIs are in the WKFMSG.H C header file. ═══ 16.2.1. WkfInitialize ═══ WkfInitialize Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfInitialize ═══ This WorkFrame/2*-provided function initializes the message routing facilities for use by an integrated tool or WorkFrame/2 object. #define INCL_WKFMSG #include extern LHANDLE APIENTRY WkfInitialize ( ULONG flConnectType, /* Connection type */ LHANDLE hClient, /* Client handle */ ULONG ulClientType, /* Router client type this client is registering as */ PSZ pszClientTitle, /* Client name */ ULONG flTypeInterest, /* Types of clients this client has interest in */ ULONG flOptions /* Registration options */ ); ═══ Parameter - flConnectType ═══ flConnectType (ULONG) - input This field determines how you want to establish the connection with the WorkFrame/2* router. Expected values for this field are: WKF_CONNECT_PM Establishes communication with the router via a Presentation Manager* (PM) message queue. This is recommended for programs that use PM services. WKF_CONNECT_SHELL Establishes communication with the router via SOM methods. This is the recommended connection type for programs that use Workplace Shell* objects. To enable communication with the router, the Workplace Shell object must define a WkfReceiveMsg SOM method. WKF_CONNECT_PIPE Establishes communication with the router via a named pipe. This is recommended for non-PM programs. Note: This communications mode has not yet been implemented. If you have an immediate need to integrate a non-PM program with WorkFrame/2, please send a note to workframe@vnet.ibm.com via the Internet. ═══ Parameter - hClient ═══ hClient (LHANDLE) - input This field identifies the client that wants to register with the router. The expected value for this field depends on the connection type specified by the flConnectType field, as illustrated by the following table: ┌────────────────────┬──────────────────────────────┐ │If flConnectType is │This field should contain... │ │set to... │ │ ├────────────────────┼──────────────────────────────┤ │WKF_CONNECT_PM │The window handle of the │ │ │Presentation Manager* │ │ │program's main window. The │ │ │router will send messages to │ │ │this window's message queue. │ ├────────────────────┼──────────────────────────────┤ │WKF_CONNECT_SHELL │The somSelf identity pointer │ │ │of the SOM object that is │ │ │registering with the router. │ ├────────────────────┼──────────────────────────────┤ │WKF_CONNECT_PIPE │The pipe handle of the named │ │ │pipe to be used to communicate│ │ │with the router. The message │ │ │router will send router │ │ │messages to this pipe. │ │ │The pipe must be a named │ │ │message pipe with duplex │ │ │access mode, and an instance │ │ │count of one. │ │ │NOTE: This communications mode│ │ │has not yet been implemented. │ │ │If you have an immediate need │ │ │to integrate a non-PM program │ │ │with WorkFrame/2, please send │ │ │a note to │ │ │workframe@vnet.ibm.com via the│ │ │Internet. │ └────────────────────┴──────────────────────────────┘ ═══ Parameter - ulClientType ═══ ulClientType (ULONG) - input This field identifies the client's type to the router. Expected values for this field are: WKF_TYPE_PROJECT The client is a WorkFrame/2* project. WKF_TYPE_FOLDER The client is a Workplace Shell* folder. WKF_TYPE_PROFILE The client is a WorkFrame/2 actions profile WKF_TYPE_MAKEMAKE The client is a makefile generation tool. WKF_TYPE_LIBRARY The client is a library and object manager. WKF_TYPE_MONITOR The client is a monitor (in the same sense as the WorkFrame/2* Monitor). WKF_TYPE_FILETOOL The client is a tool defined as a file-scoped action. WKF_TYPE_PROJTOOL The client is a tool defined as a project-scoped action. WKF_TYPE_ROUTER The client is a router. When a client registers with the WorkFrame/2* router, it can specify the types of clients it wishes to receive routed messages from (see the flTypeInterest field). The client type an object registers as determines which clients receive its messages. ═══ Parameter - pszClientTitle ═══ pszClientTitle (PSZ) - input Title string of the client. The router uses this string to identify the client when writing an entry to the WorkFrame/2* Action Log on its behalf. ═══ Parameter - flTypeInterest ═══ flTypeInterest (ULONG) - input Flag to indicate the types of clients the registering object wishes to receive messages from. Use this field to tell the router that the registering object wishes to receive broadcasted messages from the client types specified in this field. See ulClientType for a list of the valid client types for this type-interest flag. Interest types can be combined using the | (bitwise OR) operator. For example, to receive messages from base projects, actions profiles, and project- and file-scoped action clients, set this field to: WKF_TYPE_PROJECT | WKF_TYPE_PROFILE | WKF_TYPE_PROJTOOL | WKF_TYPE_FILETOOL Specify WKF_TYPE_ALL to receive messages from all client types. ═══ Parameter - flOptions ═══ flOptions (ULONG) - input Registration options flag. This field indicates whether initialization messages for this object should be written to the message log or not. Set this field to one of the following values: WKF_OPT_NONE Do not write an entry to the Action Log each time this function is called for this client. WKF_OPT_WRITELOG Write an entry to the Action Log each time this function is called for this client This function is typically called for a client each time it is opened. ═══ Return Values - WkfInitialize ═══ (LHANDLE) - return values WkfInitialize returns the following values: NULLHANDLE An error occurred. Other Router handle. ═══ Notes - WkfInitialize ═══ This function establishes a connection with the WorkFrame/2* router and determines the mode of communication with the registering client. This must be the first router call issued by any object or tool that wishes to register itself with the router. Registering with the router gives a client access to its services. This function returns a router handle, which is NULL if the initialization was not successful. The router handle is used to uniquely identify a routing session. You will need to keep track of this value to call other router APIs such as WkfNotify and WkfTerminate. ═══ Example - WkfInititalize ═══ The following pseudo-code illustrates how to use this interface to register a PM library manager program with the WorkFrame/2 router: hRouter = WkfInitialize (WKF_CONNECT_PM, /* PM connection type */ hwnd, /* My window handle */ WKF_TYPE_LIBRARY, /* Client type */ "IBM Library Manager", /* Client title */ WKF_TYPE_PROJECT | /* Listening interest */ WKF_TYPE_LIBRARY | WKF_TYPE_MONITOR | WKF_TYPE_FILETOOL | WKF_TYPE_FOLDER, WKF_OPT_NONE); /* No entry in Action Log */ if (hRouter==NULLHANDLE) ReportError ("Could not connect with WF Router."); ═══ WkfReceiveMsg ═══ WkfReceiveMsg Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - _WkfReceiveMsg ═══ If the registering client is a Workplace Shell object, it should provide this method to receive messages from the WorkFrame/2* router. SOM_Scope BOOL SOMLINK mrClient_WkfReceiveMsg ( SOMAny *somClient, /* Client's somSelf Pointer */ ULONG idMsg, /* WorkFrame/2 message ID */ PVOID pSenderInfo, /* Sender information structure */ PVOID pMsgData /* Message information structure */ ); ═══ Parameter - somClient ═══ somClient (SOMAny) - input The somSelf pointer of this client. Substitute the SOMAny type for the name of this client's SOM class when defining this function. ═══ Parameter - idMsg ═══ idMsg (ULONG) - input The message ID of the WorkFrame/2*-defined message being received. ═══ Parameter - pSenderInfo ═══ pSenderInfo (PVOID) - input Pointer to an initialized structure containing information about the sender of the message. ═══ Parameter - pMsgData ═══ pMsgData (PVOID) - input Pointer to an initialized message data structure containing information about the message. ═══ Return Values - WkfReceiveMsg ═══ (BOOL) - return values WkfReceiveMsg should return the following values: TRUE Message was received successfully, without errors. FALSE An error occurred. ═══ Notes - WkfReceiveMsg ═══ This SOM function must be defined for a SOM client that wishes to register with the WorkFrame/2* router. The router calls this function when it sends the client a message. The body of this function typically contains a CASE statement switching on all the messages that the object is interested in processing. ═══ Example - WkfReceiveMsg ═══ @@@@@ ═══ 16.2.2. WkfNotify ═══ WkfNotify Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfNotify ═══ This WorkFrame/2*-provided function sends a request or notification message to the router for execution or broadcast to existing clients. #define INCL_WKFMSG #include extern BOOL APIENTRY WkfNotify ( LHANDLE hRouter, /* Router handle */ LHANDLE hClient, /* Client handle */ ULONG idMsg, /* Message ID */ PVOID uMsgData /* Pointer to message information structure */ ); ═══ Parameter - hRouter ═══ hRouter (LHANDLE) - input Router handle returned by the WkfInitialize function. ═══ Parameter - hClient ═══ hClient (LHANDLE) - input Client handle identifying the sender of the message. Set this field to contain the same client handle that was specified when the sender called WkfInitialize to register with the router. ═══ Parameter - idMsg ═══ idMsg (LHANDLE) - input Identifier of the router message being sent. See WorkFrame/2-defined Messages for more information on router messages. ═══ Parameter - uMsgData ═══ uMsgData (PVOID) - input A pointer to an initialized data structure containing information about the message being sent. See Message Data Structures for more information on router message information structures. ═══ Return Values - WkfNotify ═══ (BOOL) - return values WkfNotify returns the following values: TRUE Message was sent successfully, without errors. FALSE An error occurred. ═══ Notes - WkfNotify ═══ Use this WorkFrame/2*-provided function to send request or notification messages to the router for execution or broadcast to interested clients. This function broadcasts messages synchronously, that is, it does not complete until the message has been processed by all interested clients. Review the list of router messages and ensure that a message is sent whenever a relevant event occurs. For example, if the client is a base project, the fact that its access method (PAM) was changed, may be of some significance to another registered client, such as an actions profile, if it defines actions that cannot be executed in the file system supported by the new PAM. In this case, the client should send the router the WKFM_CLIENTCHANGED message, citing the WKF_PROJECT_ACCESSMETHOD change flag in the WKF_CHANGEINFO data structure. ═══ Example - WkfNotify ═══ The following pseudo-code illustrates how a PM program could use this interface to broadcast a WKFM_FILECHANGED message: /* Build message info structure */ PWKF_FILECHANGEINFO pMsgInfo; ULONG cSize; /* Allocate message data */ cSize = sizeof(PWKF_FILECHANGEINFO) + sizeof(szFileNames) + 1; pMsgInfo = (PWKF_FILECHANGEINFO) WkfAllocMsgData (cSize); j = sprintf(pMsgInfo->szParm, "%s"WKF_LIST_DELIM"%s", szPrjFile, szChangedFile); pMsgInfo->cb = cSize; /* Now send message */ WkfNotify ( hRouter, /* Router handle */ hwnd, /* My window handle */ WKFM_FILECHANGED, /* Message ID */ (PVOID)pMsgInfo); /* Pointer to message structure */ /* Always free message data after sending it */ WkfFreeMsgData (pMsgData); ═══ 16.2.3. WkfAccessMsgData ═══ WkfAccessMsgData Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfAccessMsgData ═══ If a message queue is used for client-router communication, use this interface to obtain permission to access the received message data. #define INCL_WKFMSG #include extern BOOL APIENTRY WkfAccessMsgData ( PVOID pMsgData /* Pointer to message information structure */ ); ═══ Parameter - pMsgData ═══ pMsgData (PVOID) - input Pointer to the message information structure to access. ═══ Return Values - WkfAccessMsgData ═══ (BOOL) - return values WkfAccessMsgData returns the following values: TRUE Message data successfully accessed. FALSE An error occurred. ═══ Notes - WkfAccessMsgData ═══ Use this function to obtain access incoming message data. Message data may reside in shared memory, thus permission to access shared memory object must first be granted. Call this function after receiving an incoming message from the router. ═══ Example - WkfAccessMsgData ═══ The following pseudo-code illustrates how this interface could be used by a client registered via the PM connection type: : /* Handle MOVED and RENAMED message cases in window procedure */ case WKFM_CLIENTRENAMED: case WKFM_CLIENTMOVED: PWKF_RENAMEINFO pMsgData PSZ pszNewName, pszOldName; /* Make sure we can access message data */ if ( WkfAccessMsgData (mp2) ) { pMsgData = (PWKF_RENAMEINFO)mp2; /* Cast to msg info structure type */ /* Access message data by their offsets */ pszOldName = pMsgData->szParm + strlen(pMsgData->MsgParm) + 1; pszNewName = pszOldName + strlen(pszOldName) + 1; : < Process message data > : } return ((MRESULT) TRUE ); ═══ 16.2.4. WkfAllocMsgData ═══ WkfAllocMsgData Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfAllocMsgData ═══ Use this WorkFrame/2*-provided function to allocate space for outgoing message data. A pointer to the newly-allocated space is returned. #define INCL_WKFMSG #include extern PVOID APIENTRY WkfAllocMsgData ( ULONG cbAlloc /* Number of bytes to be allocated */ ); ═══ Parameter - cbAlloc ═══ cbAlloc (ULONG) - input Number of bytes to allocate for the message information structure. ═══ Return Values - WkfAllocMsgData ═══ (PVOID) - return values WkfAccessMsgData returns the following values: NULL Data unsuccessfully allocated. Other Pointer to newly-allocated memory. ═══ Notes - WkfAllocMsgData ═══ Use this WorkFrame/2*-provided function to allocate memory for message data to be sent to the router. Call this function before sending a message to the router using WkfNotify, and always call WkfFreeMsgData to free message data after sending it. ═══ Example - WkfAllocMsgData ═══ The following pseudo-code illustrates how to use this interface: /* Build message info structure */ PWKF_FILECHANGEINFO pMsgInfo; ULONG cSize; /* Allocate message data */ cSize = sizeof(PWKF_FILECHANGEINFO) + sizeof(szFileNames) + 1; pMsgInfo = (PWKF_FILECHANGEINFO) WkfAllocMsgData (cSize); j = sprintf(pMsgInfo->szParm, "%s"WKF_LIST_DELIM"%s", szPrjFile, szChangedFile); pMsgInfo->cb = cSize; /* Now send message */ WkfNotify ( hRouter, /* Router handle */ hwnd, /* My window handle */ WKFM_FILECHANGED, /* Message ID */ (PVOID)pMsgInfo); /* Pointer to message structure */ /* Always free message data after sending it */ WkfFreeMsgData (pMsgData); ═══ 16.2.5. WkfFreeMsgData ═══ WkfFreeData Select an item: Function Syntax Notes Examples ═══ Syntax - WkfFreeMsgData ═══ Use this WorkFrame/2*-provided function to free an allocated message information structure. #define INCL_WKFMSG #include extern VOID APIENTRY WkfFreeMsgData ( PVOID pMsgData /* Pointer to message information structure */ ); ═══ Parameter - pMsgData ═══ pMsgData (PVOID) - input Pointer to the message information structure to free. ═══ Notes - WkfFreeMsgData ═══ Use this WorkFrame/2*-provided function to release a message information structure that has been allocated using WkfAllocMsgData. Do not use any other memory functions to free the message structure. The structure may have been allocated in shared memory and therefore needs to be released accordingly. Call this function to free a message information structure after you no longer need access to it. ═══ Example - WkfFreeMsgData ═══ The following pseudo-code illustrates how this interface could be used by a client registered via the PM connection type: /* Build message info structure */ PWKF_FILECHANGEINFO pMsgInfo; ULONG cSize; /* Allocate message data */ cSize = sizeof(PWKF_FILECHANGEINFO) + sizeof(szFileNames) + 1; pMsgInfo = (PWKF_FILECHANGEINFO) WkfAllocMsgData (cSize); j = sprintf(pMsgInfo->szParm, "%s"WKF_LIST_DELIM"%s", szPrjFile, szChangedFile); pMsgInfo->cb = cSize; /* Now send message */ WkfNotify ( hRouter, /* Router handle */ hwnd, /* My window handle */ WKFM_FILECHANGED, /* Message ID */ (PVOID)pMsgInfo); /* Pointer to message structure */ /* Always free message data after sending it */ WkfFreeMsgData (pMsgData); ═══ 16.2.6. WkfTerminate ═══ WkfTerminate Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfTerminate ═══ Use this WorkFrame/2*-provided function to terminate communication with the router. #define INCL_WKFMSG #include extern BOOL APIENTRY WkfTerminate ( LHANDLE hRouter, /* Router handle */ LHANDLE hClient /* Client handle */ ); ═══ Parameter - hRouter ═══ hRouter (LHANDLE) - input Router handle returned by the WkfInitialize function. ═══ Parameter - hClient ═══ hClient (LHANDLE) - input Client handle identifying the sender of the message. Set this field to contain the same client handle that was specified when the sender issued the WkfInitialize function to register with the router. ═══ Return Values - WkfTerminate ═══ (BOOL) - return values WkfTerminate returns the following values: TRUE Communication with the message router successfully terminated. FALSE An error occurred. ═══ Notes - WkfTerminate ═══ Use this WorkFrame/2*-provided function to deregister the client with the router. Call this function as part of the normal processing for termination of the client object. ═══ Example - WkfTerminate ═══ The following pseudo-code illustrates how to use this interface within the window procedure of a PM application: /* Terminate router connection during the processing of a "CLOSE" */ /* or "EXIT" command or message. */ : case WM_CLOSE: hRouter = (LHANDLE) WinQueryWindowUlong (hwnd, /* Get router handle from */ QWL_USER) /* window words */ if (hRouter != NULLHANDLE) fSuccess = WkfTerminate (hRouter, hwnd); : break; ═══ 16.3. Router Messages ═══ This section describes the messages that can be sent to or received from the WorkFrame/2* router. Router messages can categorized into the following groups: Notification Messages o Messages dealing with clients - WKFM_CLIENTCHANGED - WKFM_CLIENTRENAMED - WKFM_CLIENTDELETED - WKFM_CLIENTMOVED - WKFM_INITIALIZE o Messages dealing with files - WKFM_FILECHANGED - WKFM_FILERENAMED - WKFM_FILEDELETED o Messages dealing with actions - WKFM_APPSTARTNOTIFY - WKFM_APPTERMNOTIFY - WKFM_ACTIONSTART - WKFM_ACTIONEND Request Messages o Messages dealing with actions - WKFM_EXECUTEACTION o Messages for writing to the Action Log - WKFM_LOGMESSAGE - WKFM_LOGERROR ═══ 16.3.1. WKFM_ACTIONEND ═══ Message ID WKFM_ACTIONEND Cause A client sends this message to the router when an action that was started on its behalf ends. For example, the WorkFrame/2* Monitor client would send this message after a compile action finishes processing on one or more project parts. Information structure WKF_ACTIONENDINFO ═══ 16.3.2. WKFM_ACTIONSTART ═══ Message ID WKFM_ACTIONSTART Cause A client sends this message to the router when an action is started on its behalf. For example, the WorkFrame/2* Monitor client would send this message after a link action that was invoked on one or more project parts has finishes processing. Information structure WKF_ACTIONSTARTINFO ═══ 16.3.3. WKFM_APPSTARTNOTIFY ═══ Message ID WKFM_APPSTARTNOTIFY Cause A client sends this message to the router when an application has been started. To the router, an application is a program that was started as a result of another action. For example, a make action could send this message for a compile or link application that it starts. A WKFM_ACTIONSTART message message would be sent for the make action when it starts, as well as a WKFM_APPSTARTNOTIFY message for each application started within the make. Information structure WKF_APPSTARTINFO ═══ 16.3.4. WKFM_APPTERMNOTIFY ═══ Message ID WKFM_APPTERMNOTIFY Cause A client sends this message to the router when an application has terminated. To the router, an application is a program that was started as a result of another action. For example, a make action could send this message for a terminated compile or link application that it had started. A single WKFM_ACTIONEND message would be sent for the make action when it ends, as well as a WKFM_APPTERMNOTIFY message for each application started within the make as it terminates. Information structure WKF_APPTERMINFO ═══ 16.3.5. WKFM_CLIENTCHANGED ═══ Message ID WKFM_CLIENTCHANGED Cause A client sends this message to the router when it has been changed. For example, a base project client would send this message when one or more of its settings are changed. Information structure WKF_CHANGEINFO ═══ 16.3.6. WKFM_CLIENTDELETED ═══ Message ID WKFM_CLIENTDELETED Cause A client sends this message to the router when it has been deleted. Information structure WKF_DELETEINFO ═══ 16.3.7. WKFM_CLIENTMOVED ═══ Message ID WKFM_CLIENTMOVED Cause A client sends this message to the router when its physical file representation has been moved. Take an actions profile object as an example. An actions profile is represented by a single file on disk, under the OS/2 Desktop directory. Its location on the desktop determines its physical path on the disk. If the actions profile object is moved from one folder to another, it's physical file representation is also moved and so it should send this message to the router to inform interested clients. Information structure WKF_MOVEINFO ═══ 16.3.8. WKFM_CLIENTRENAMED ═══ Message ID WKFM_CLIENTRENAMED Cause A client sends this message to the router when it has been renamed. Information structure WKF_RENAMEINFO ═══ 16.3.9. WKFM_EXECUTEACTION ═══ Message ID WKFM_EXECUTEACTION Cause A client sends this message to the router to tell the WorkFrame/2* program to execute an action. The program to be executed must be present in the actions profile of the project. If no action name is specified in the WKF_EXECUTEINFO data structure, the default action for the specified action class will be executed. The router also broadcasts a WKFM_ACTIONSTART notification message to interested clients when it receives this message. For example, as part of some special processing, a debugger tool may need to call a compiler. As a routing client, it can send this message to have the router start a COMPILE action on its behalf. Information structure WKF_EXECUTEINFO ═══ 16.3.10. WKFM_FILECHANGED ═══ Message ID WKFM_FILECHANGED Cause A client sends this message to the router when a file has changed. For example, a compiler (client type WKF_TYPE_FILETOOL) could send this message when it produces a new .EXE file; a linker could send this message for each .OBJ file that it replaces. Information structure WKF_FILECHANGEINFO ═══ 16.3.11. WKFM_FILEDELETED ═══ Message ID WKFM_FILEDELETED Cause A client sends this message to the router when an associated file has been deleted. For example, a base project client would send this message once for every deleted project part. Information structure WKF_FILEDELETEINFO ═══ 16.3.12. WKFM_FILERENAMED ═══ Message ID WKFM_FILERENAMED Cause A client sends this message to the router when a file has been renamed. For example, a base project client would send this message when a project part is renamed. Information structure WKF_FILERENAMEINFO ═══ 16.3.13. WKFM_INITIALIZE ═══ Message ID WKFM_INITIALIZE Cause The message router broadcasts this message when a client registers with the router using WkfInitialize. This message should not be sent to the router by registered clients. Information structure WKF_INITIALIZEINFO ═══ 16.3.14. WKFM_LOGERROR ═══ Message ID WKFM_LOGERROR Cause A client sends this message to the router to tell the WorkFrame/2* program to write an error message to the Action Log. Information structure WKF_ERRORMSGINFO ═══ 16.3.15. WKFM_LOGMESSAGE ═══ Message ID WKFM_LOGMESSAGE Cause A client sends this message to the router to tell the WorkFrame/2* program to write an information message to the Action Log. Information structure WKF_LOGMSGINFO ═══ 17. Installation Support ═══ This section describes the WorkFrame/2*-provided APIs that support tool installation tasks. ═══ 17.1. Installation Support APIs ═══ This section descibes the WorkFrame/2*-provided APIs for installing WorkFrame/2-integrated tools. The function prototypes and constant declarations for the actions profile APIs are in the WKFINS.H C header file. ═══ 17.1.1. WkfQueryInstalledVersion ═══ WkfQueryInstalledVersion Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfQueryInstalledVersion ═══ This WorkFrame/2*-provided function returns the version of the WorkFrame/2 product currently installed on the system. #define INCL_WKFINS #include BOOL _System WkfQueryInstalledVersion ( PSZ pszDirectory, /* WF installation directory - returned */ ULONG ulDirectory, /* Size, in bytes, of pszDirectory buffer */ PULONG *pulMajorVersion, /* Major version number - returned */ PULONG *pulMinorVersion, /* Minor version number - returned */ BOOL OnlyVersion1 /* Look for version 1.x only */ ); ═══ Parameter - pszDirectory ═══ pszDirectory (PSZ) - output On exit, this field contains the fully qualified ASCIIZ path name of the directory where WorkFrame/2 is currently installed in the system. If the OnlyVersion1 field is set to TRUE, this field contains the directory in which Version 1.x of the WorkFrame/2 product is installed. Otherwise, this field contains the directory in which the latest WorkFrame/2 version is installed. Allocate this buffer to a size of at least CCHMAXPATH large to ensure success. ═══ Parameter - ulDirectory ═══ ulDirectory (PSZ) - output On exit, this field contains the actual size, in bytes, of the field pointed to by pszDirectory. ═══ Parameter - pulMajorVersion ═══ pulMajorVersion (PSZ) - output On exit, this field contains the major version number of the WorkFrame/2 product installed in pszDirectory. For example, this field would contain the number 2 for WorkFrame/2 Version 2.1. ═══ Parameter - pulMinorVersion ═══ pulMinorVersion (PSZ) - output On exit, this field contains the minor version number of the WorkFrame/2 product installed in pszDirectory. For example, this field would contain the number 1 for WorkFrame/2 Version 2.1. ═══ Parameter - OnlyVersion1 ═══ OnlyVersion1 (BOOL) - input If this field is set to TRUE, then this function will only search for Version 1.x of the WorkFrame/2* product on the current system. If this field is set to FALSE, this function searches for the latest version of WorkFrame/2 currently on the system. ═══ Return Values - WkfQueryInstalledVersion ═══ (BOOL) - return values WkfQueryInstalledVersion returns the following values: TRUE It is determined that there is a version of the WorkFrame/2 product installed on the system. Note that if OnlyVersion1 is set to TRUE, this function will only return TRUE if WorkFrame/2 Version 1.x is installed on the system. FALSE It is determined that the requested version of WorkFrame/2 is not installed on the system. Note that if OnlyVersion1 is set to TRUE, this function will only return true if WorkFrame/2 Version 1.x is not present on the system. ═══ Notes - WkfQueryInstalledVersion ═══ This WorkFrame/2*-provided function detects whether or not WorkFrame/2 is installed on the system. You can use this function to determine whether or not WorkFrame/2 support for your tool should be installed. Set OnlyVersion1 to TRUE if you want to search only for Version 1.x of the WorkFrame/2 product. Otherwise, set it to FALSE to search for the most current version. If the requested version of WorkFrame/2 is found, this function returns the WorkFrame/2 installation directory, and the major and minor release numbers of the version found. Note: This function is not present in any of the shipped WorkFrame/2 DLLs. The object module containing this code is statically available in WF21.LIB, included with this integration kit. This function can therefore be called whether or not WorkFrame/2 is installed on the system. ═══ Example - WkfQueryInstalledVersion ═══ The following pseudo-code illustrates how this interface might be used: @@@@@@ ═══ 17.1.2. WkfSetDefaultOption ═══ WkfSetDefaultOption Select an item: Function Syntax Return Values Notes Examples ═══ Syntax - WkfSetDefaultOption ═══ This WorkFrame/2*-provided function sets default options for an action that uses the default actions support (Options) DLL, DDE3DEF2. #define INCL_WKFINS #include BOOL _System WkfSetDefaultOption ( HAB hAB, /* Caller's anchor block, or NULLHANDLE */ PSZ pszActionClass, /* Tool's action class, e.g. "EDIT" */ PSZ pszEXEName, /* Unqualified program file name, no extension */ PSZ pszParameters, /* Program parameters */ PSZ pszErrorTemplate, /* Error template */ PSZ pszPromptOnRun, /* Prompt user for parameters? */ PSZ pszSupportDDE /* Tool supports WF DDE protocols? */ ); ═══ Parameter - hAB ═══ hAB (HAB) - input Caller's anchor block, or NULLHANDLE. If this field is set to NULLHANDLE, then this function will create its own temporary anchor block to open the DDE3DEF2 profile. This field is a required parameter of the PrfOpenProfile OS/2* API called by this function. ═══ Parameter - pszActionClass ═══ pszActionClass (PSZ) - input The tool's action class name, for example, "EDIT" or "COMPILE". ═══ Parameter - pszEXEName ═══ pszEXEName (PSZ) - input The tool's unqualified program file name. Specify this name without a file name extension, for example, "EPM" or "ICC". ═══ Parameter - pszParameters ═══ pszParameters (PSZ) - input The parameters to run the program specified in pszEXEName, for example, "/W %a %z". See Substitution Variables for more information on how you can specify program parameters using WorkFrame/2 substitution variables. This parameter maps to the Parameters entry field in the default options dialog. ═══ Parameter - pszErrorTemplate ═══ pszErrorTemplate (PSZ) - input The error template for the tool's error messages. This field is only applicable to tools, such as compilers and linkers, that produce output with error messages, and can run in the Monitor window. For example, specify this template: (%f : %i, %c) %t for an error message of the form: (MYFILE.C : 238, 23) Text of the error message. When the user double-clicks on an error or warning message in the Monitor window, DDE3DEF2, the default Options DLL, uses The error template to parse the error message into: o The file name in which the error occurred (represented by %f) o The line at which the error occurred (represented by %i) o The column at which the error occurred (represented by %c) o The text of the error message (represented by %t) This parameter maps to the Error template entry field in the default options dialog for most action classes. ═══ Parameter - pszPromptOnRun ═══ pszPromptOnRun (PSZ) - input This field is expected to contain one of the following values: WKFDEF2_PROMPT_YES Prompt the user for parameters prior to starting the action. This gives the user a chance to modify the parameters before the action is started. WKFDEF2_PROMPT_NO Invoke the action without prompting the user for parameters. This parameter maps to the Prompt check box in the default options dialogs. ═══ Parameter - pszSupportDDE ═══ pszSupportDDE (PSZ) - input This field is expected to contain one of the following values: WKFDEF2_EDITDDE_YES The tool supports WorkFrame/2 DDE protocols. This value is only applicable to EDIT class tools WKFDEF2_EDITDDE_NO The tool is not an EDIT class tool, or is an EDIT class tool that does not support WorkFrame/2 DDE protocols. This parameter maps to the Send errors to editor check box in the default options dialog for EDIT class actions. ═══ Return Values - WkfSetDefaultOption ═══ (BOOL) - return values WkfSetDefaultOption returns the following values: TRUE Default options successfully set. FALSE Unable to set default options. ═══ Notes - WkfSetDefaultOptions ═══ Use this WorkFrame/2*-provided function to set the default options for the tool if it is using the default actions support (Options) DLL, DDE3DEF2. Many of this function's parameters map to controls in the default options dialogs. To see what these dialogs look like, set the options for any action that uses DDE3DEF2 for its Options DLL. For example, look at the options dialog for the Hello World WorkFrame/2 sample project's MAKE, RUN, or EDIT file-scoped actions (go to the Actions page of Hello World's Settings notebook and click on the Options push button). Note: This function is not available in any of the DLLs shipped with the WorkFrame/2 program. The object module containing this code is statically available in the WF21.LIB file included with this integration kit. ═══ Example - WkfSetDefaultOptions ═══ The following pseudo-code illustrates how this interface might be used: @@@@@@ ═══ 18. Building Integrated Code ═══ This section tells you how to build your code for WorkFrame/2* integration. If you are building an actions support or PAM DLL, note that you can combine support for several tools in one actions support (or Options) DLL. The entrypoints for a single PAM can also be included in the same DLL, or can be made available in a separate DLL. Header Files to Include Include the master header file WKF.H once in the .C file within each compile module, and then define one or more of the following macros as appropriate to the interfaces you require: ┌──────────────────┬─────────────────────────────────────────────────────────┐ │ Macro │ Includes │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFMSG │Router header (WKFMSG.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFPRF │Actions profile header (WKFPRF.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFPRJ │Base project header (WKFPRJ.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WF │Router, base project, and actions profile headers │ │ │(WKFMSG.H, WKFPRF.H, and WKFPRJ.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFOPT │Actions support header (WKFOPT.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFPAM │Project access method header (WKFPAM.H) │ ├──────────────────┼─────────────────────────────────────────────────────────┤ │INCL_WKFINS │Installation support header (WKFINS.H) │ └──────────────────┴─────────────────────────────────────────────────────────┘ For example, say you are fully integrating a set of tools into WorkFrame/2. You are providing both an actions support and PAM DLL, registering your tools with the router, and creating an actions profile and sample projects. You might organize your files this way: Main program: TOOLMAIN.C #include "toolrout.h" #include "toolinst.h" #include wkf.h Actions support interfaces: TOOLACTS.H #define INCL_WKFOPT /* Include action support header WKFOPT.H */ TOOLACTS.C #include "toolacts.h" #include "wkf.h" PAM interfaces TOOLPAM.H #define INCL_WKFPAM /* Include PAM header WKFPAM.H */ TOOLPAM.C #include "toolpam.h" #include "wkf.h" Router communication TOOLROUT.H #define INCL_WKFMSG /* Include router header WKFMSG.H */ TOOLROUT.C #include "toolrout.h" #include "wkf.h" Installing INSTPRJ.H #define INCL_WKFPRJ /* Include project header WKFPRJ.H */ #define INCL_WKFINS /* Include installation support header WKFINMS.H */ INSTPRF.H #define INCL_WKFPRF /* Include actions profile header WKFPRF.H */ #define INCL_WKFINS TOOLINST.C #include "toolinst.h" #include "wkf.h" Note that as required, wkf.h is included only once within each compile module (wkf.h is not included in every header file). The INCL_ macros are used to include other integration header files as appropriate. Creating the Module Definition File Your module definition file should include these elements as shown in the sample .DEF file for an actions support DLL below: LIBRARY WFTOOL.DLL INITINSTANCE TERMINSTANCE NEWFILES DESCRIPTION 'DLL file containing actions support entrypoints' DATA MULTIPLE NONSHARED CODE LOADONCALL EXPORTS WKFQUERYTOOLOPTIONS WKFQUERYTOOLTARGET WKFTOOLTERMINATE WKFTOOLPARSEERROR WKFQUERYTOOLHELPFILE WKFQUERYTOOLRESOURCEID WKFQUERYTOOLDDE To provide a PAM in the same DLL, add the PAM entrypoints to the actions support entrypoints under the EXPORTS statement of the module definition file. Compile and Link Options You must specify these options when compiling the source to build an actions support or PAM DLL: /Gm You must write your code such that it is re-entrant. /Ge- Build a .DLL file. You may specify other options as long as they do not conflict with these. If you are not using the C Set ++* compiler, specify the corresponding options on your compiler. Libraries to Link To Link to these libraries as appropriate: WKF21.LIB All integrating tools should link to this library. It provides access to the base project, WorkFrame/2 message router, and actions profiles. It also contains the statically linkable object module for querying the installed WorkFrame/2 directory. WKFBPM21.LIB Provides access to the services supplied by the basic PAM (DDE3BPAM.DLL) shipped with WorkFrame/2. Link to this library to chain to the basic PAM when you are providing your own PAM. WKFDEF21.LIB You should link to this library only if you are not providing your own actions support DLL, and wish to rely on the default options DLL, DDE3DEF2, to provide actions support for your tool. This library contains the statically linkable object module for setting default options for a tool that uses the default Options DLL, DDE3DEF2. It also provides access to the default tool options support (DDE3DEF2.DLL) that is shipped with WorkFrame/2. ═══ 19. General Constants ═══ The following table shows the general-purpose WorkFrame/2-defined constants and their meaning: ┌───────────────────────────────────┬──────────────────────────────────────────────────────────────────┐ │ Constant │ Meaning │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │V2_APP │Application name for storing data in the OS2.INI file. │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WF_DIRKEY │Data key name under which the WorkFrame/2 (Version 1.x and 2.x) │ │ │installation directory name is stored in the OS2.INI file. │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKFDLL_ACTPRF │Name of WorkFrame/2 DLL containing the actions profile interfaces.│ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKFDLL_PJIO │Name of WorkFrame/2 DLL containing the base project I/O │ │ │interfaces. │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKFDLL_ROUTER │Name of WorkFrame/2 DLL containing the router interfaces. │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_ACTION_HANDLE_RESERVED │WorkFrame/2-initiated action handle │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_ACTKEY_TEMPLATE │Template used to generate an application key for storing options │ │ │within a project file. An application key is used to identify a │ │ │specific action within an actions profile. It is of the form │ │ │"::". │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_OPTKEY_TEMPLATE │Template used to generate a key used to store options for a │ │ │specific action within an actions profile or project. It is of │ │ │the form │ │ │"::::" │ │ │where is one of WKF_SCOPE_PROJECT or WKF_SCOPE_FILE. │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_LIST_DELIM │Character used to delimit fields in WorkFrame/2 list strings │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_LIST_DELIMSTR │Character string used to delimit fields in WorkFrame/2 list │ │ │strings │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_ACTKEYLEN │Maximum action key name length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_APINAMELEN │Maximum entrypoint name length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_CLASSLEN │Maximum class name length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_ENVSTRLEN │Maximum environment string length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_ENVVARLEN │Maximum environment variable length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_HELPCMDLEN │Maximum help command-line string length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_INVKEYLEN │Maximum invocation string key length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_MASKLIST │Maximum mask list string length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_NAMELEN │Maximum general name length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_OPTKEYLEN │Maximum action option key name length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_PARMLIST │Maximum parameter list length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_PATHLIST │Maximum path list string length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MAX_TEMPLIST │Maximum general list length │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MTR_AUTOCLOSE │Monitor options flag - close monitor if action terminates without │ │ │error │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MTR_MINIMIZE │Monitor options flag - start monitor minimized │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_MTR_MULTIPLE │Monitor options flag - multiple, concurrent monitors │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_OPTIONS_APPNAME │Application name for the action options │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_PREFIX │Used as a WorkFrame/2 name prefix │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │DDE3_PREFIX │Used as a WorkFrame/2 name prefix │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_RUN_FULLSCREEN │Run mode - full-screen session │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_RUN_MONITOR │Run mode - WorkFrame/2 monitor session │ ├───────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ │WKF_RUN_WINDOW │Run mode - Window session │ └───────────────────────────────────┴──────────────────────────────────────────────────────────────────┘ Note: Constants with the name prefix WKF_MAX_ define the various maximum string limits used by the WorkFrame/2 program. They all include one byte for the terminating NULL character. ═══ 20. Data Types ═══ This section describes the WorkFrame/2* Integration Toolkit data types in C language. ═══ 20.1. APWKF_ACTION ═══ APWKF_ACTION - array of pointers to a PWKF_ACTION data structure. typedef PWKF_ACTION *APWKF_ACTION ═══ 20.2. APWKF_ENVIRON ═══ APWKF_ENVIRON - array of pointers to a PWKF_ENVIRON data structure typedef PWKF_ENVIRON *APWKF_ENVIRON; ═══ 20.3. FILEFINDBUF3 ═══ FILEFINDBUF3 - An OS/2*-defined type defining 32-bit level 1 file information, used without extended attributes. Each WKFPAM_PART structure contains a FILEFINDBUF3 element that describes a project part. This structure is returned by the control program APIs, DosFindFirst and DosFindNext. typedef struct _FILEFINDBUF3 { ULONG oNextEntryOffset; /* Always set to zero for WKFPAM_PART */ FDATE fdateCreation; FTIME ftimeCreation; FDATE fdateLastAccess; FTIME ftimeLastAccess; FDATE fdateLastWrite; FTIME ftimeLastWrite; ULONG cbFile; /* Actual bytes used by file */ ULONG cbFileAlloc; /* Bytes allocated for file */ ULONG attrFile; /* File attributes */ UCHAR cchName; /* Number of characters in file name */ CHAR achName[CCHMAXPATHCOMP]; /* File name */ } FILEFINDBUF3; For more information, please refer to the on-line Control Program Guide and Reference book from the IBM* Developer's Toolkit. ═══ 20.4. HAM ═══ HAM - project access method (PAM) handle. A HAM value uniquely identifies a project and its corresponding project access method. typedef LHANDLE HAM; Note: The HAM value is returned by and used solely by internal PAM functions. Functions external to the PAM should not rely on the HAM value to uniquely identify a project and its access method. ═══ 20.5. LIST_OF_SOURCE ═══ LIST_OF_SOURCE - source files list structure used as a parameter to the WkfQuery...Target actions support API typedef _Packed struct _LIST_OF_SOURCE { ULONG ulNumOfEntries; /* Number of selected files */ ULONG ulNumUsed; /* Number of files used */ SOURCE_ENTRY stObject[1]; /* Array of source structures */ } LIST_OF_SOURCE; ═══ 20.6. LIST_OF_TARGET ═══ LIST_OF_TARGET - target files list structure; used as a parameter to the WkfQuery...Target actions support API typedef _Packed struct _LIST_OF_TARGET { ULONG ulNumOfEntries; /* Number of entries in the buffer */ ULONG ulBufferSize; /* Actual size of cBuffer */ char cBuffer[1]; /* List of files produced by the action */ } LIST_OF_TARGET; ═══ Field - cBuffer ═══ cBuffer (char) A string containing a list of file names in the following form: (filename_1)(filename_2)...(filename_n)\0 where each filename_x is a null-terminated string. ═══ 20.7. LIST_OF_DEPEND ═══ LIST_OF_DEPEND - dependency files list structure; used as a parameter to the WkfQuery...Target options API typedef _Packed struct _LIST_OF_DEPEND { ULONG ulNumOfEntries; /* Number of entries in the buffer */ ULONG ulBufferSize; /* Size of cBuffer, in bytes */ char cBuffer[1]; /* List of dependency files */ } LIST_OF_DEPEND; ═══ 20.8. PHAM ═══ PHAM - pointer to a HAM project identifier typedef HAM *PHAM; ═══ 20.9. PWKF_ACTION ═══ PWKF_ACTION - pointer to a WKF_ACTION data structure typedef WKF_ACTION *PWKF_ACTION; ═══ 20.10. PWKF_ACTIONS ═══ PWKF_ACTIONS - pointer to a WKF_ACTIONS data structure typedef WKF_ACTIONS *PWKF_ACTIONS; ═══ 20.11. PWKF_ACTIONENDINFO ═══ PWKF_ACTIONENDINFO - pointer to a WKF_ACTIONENDINFO data structure typedef WKF_ACTIONENDINFO *PWKF_ACTIONENDINFO; ═══ 20.12. PWKF_ACTIONSTARTINFO ═══ PWKF_ACTIONSTARTINFO - pointer to a WKF_ACTIONSTARTINFO data structure typedef WKF_ACTIONSTARTINFO *PWKF_ACTIONSTARTINFO; ═══ 20.13. PWKF_APPSTARTINFO ═══ PWKF_APPSTARTINFO - pointer to a WKF_APPSTARTINFO data structure typedef WKF_APPSTARTINFO *PWKF_APPSTARTINFO; ═══ 20.14. PWKF_APPTERMINFO ═══ PWKF_APPTERMINFO - pointer to a WKF_APPTERMINFO data structure typedef WKF_APPTERMINFO *PWKF_APPTERMINFO; ═══ 20.15. PWKF_CHANGEINFO ═══ PWKF_CHANGEINFO - pointer to a WKF_CHANGEINFO data structure typedef WKF_CHANGEINFO *PWKF_CHANGEINFO; ═══ 20.16. PWKF_DELETEINFO ═══ PWKF_DELETEINFO - pointer to a WKF_DELETEINFO data structure typedef WKF_DELETEINFO *PWKF_DELETEINFO; ═══ 20.17. PWKF_ENVIRON ═══ PWKF_ENVIRON - pointer to a WKF_ENVIRON data structure typedef WKF_ENVIRON *PWKF_ENVIRON; ═══ 20.18. PWKF_ENVIRONS ═══ PWKF_ENVIRONS - pointer to a WKF_ENVIRONS data structure typedef WKF_ENVIRONS *PWKF_ENVIRONS; ═══ 20.19. PWKF_EXECUTEINFO ═══ PWKF_EXECUTEINFO - pointer to a WKF_EXECUTEINFO data structure typedef WKF_EXECUTEINFO *PWKF_EXECUTEINFO; ═══ 20.20. PWKF_FILECHANGEINFO ═══ PWKF_FILECHANGEINFO - pointer to a WKF_FILECHANGEINFO data structure typedef WKF_FILECHANGEINFO *PWKF_FILECHANGEINFO; ═══ 20.21. PWKF_FILEDELETEINFO ═══ PWKF_FILEDELETEINFO - pointer to a WKF_DELETEINFO data structure typedef WKF_FILEDELETEINFO *PWKF_FILEDELETEINFO; ═══ 20.22. PWKF_FILERENAMEINFO ═══ PWKF_FILERENAMEINFO - pointer to a WKF_FILERENAMEINFO data structure typedef WKF_FILERENAMEINFO *PWKF_FILERENAMEINFO; ═══ 20.23. PWKF_INITIALIZEINFO ═══ PWKF_INITIALIZEINFO - pointer to a WKF_INITIALIZEINFO data structure typedef WKF_INITIALIZEINFO *PWKF_INITIALIZEINFO; ═══ 20.24. PWKF_LOGMSGINFO ═══ PWKF_LOGMSGINFO - pointer to a WKF_LOGMSGINFO data structure typedef WKF_LOGMSGINFO *PWKF_LOGMSGINFO; ═══ 20.25. PWKF_ERRORMSGINFO ═══ PWKF_ERRORMSGINFO - pointer to a WKF_ERRORMSGINFO data structure typedef WKF_ERRORMSGINFO *PWKF_ERRORMSGINFO; ═══ 20.26. PWKF_MOVEINFO ═══ PWKF_MOVEINFO - pointer to a WKF_MOVEINFO data structure typedef WKF_MOVEINFO *PWKF_MOVEINFO; ═══ 20.27. PWKF_RENAMEINFO ═══ PWKF_RENAMEINFO - pointer to a WKF_RENAMEINFO data structure typedef WKF_RENAMEINFO *PWKF_RENAMEINFO; ═══ 20.28. PWKF_SENDERINFO ═══ PWKF_SENDERINFO - pointer to a WKF_SENDERINFO data structure typedef WKF_SENDERINFO *PWKF_SENDERINFO; ═══ 20.29. PWKF_TYPE ═══ PWKF_TYPE - pointer to a WKF_TYPE data structure typedef WKF_TYPE *PWKF_TYPE; ═══ 20.30. PWKF_TYPES ═══ PWKF_TYPES - pointer to a WKF_TYPES data structure typedef WKF_TYPES *PWKF_TYPES; ═══ 20.31. PWKFBASEPROJECT ═══ PWKFBASEPROJECT - pointer to a WKFBASEPROJECT data structure typedef WKFBASEPROJECT *PWKFBASEPROJECT; ═══ 20.32. PWKFPAM_PART ═══ PWKFPAM_PART - pointer to a WKFPAM_PART data structure typedef WKFPAM_PART *PWKFPAM_PART; ═══ 20.33. SOURCE_ENTRY ═══ SOURCE_ENTRY - single source file entry in a LIST_OF_SOURCE structure typedef _Packed struct _SOURCE_ENTRY { ULONG fUsed; /* File usage flag */ PSZ szFileName; /* File name string */ } SOURCE_ENTRY; ═══ Field - fUsed ═══ fUsed (ULONG) Indicates whether or not a file is used by a particular action. It should contain one of three possible values: 0 WKF_QT_FILE_NOTUSED File is not processed by action. 1 WKF_QT_FILE_USED File is processed and required by action. 2 WKF_QT_FILE_DISCARD File is processed and to be discarded. ═══ 20.34. WKF_ACTION ═══ WKF_ACTION - action information structure typedef _Packed struct _WKF_ACTION { PSZ pszActionName; /* Action name */ PSZ pszActionClass; /* Action class */ PSZ pszCommand; /* Action command */ PSZ pszSrcMask; /* Action source masks or types (to change to pszSrcTypes) */ PSZ pszTgtMask; /* Action target masks or types (to change to pszTgtTypes) */ PSZ pszDllName; /* Action options DLL name */ PSZ pszDllEntryName; /* Options DLL entrypoint name */ PSZ pszHelpCmd; /* Action help command string */ PSZ pszHelpTopic; /* Action help topic string */ UCHAR ucActionType; /* Action type */ UCHAR ucActionScope; /* Action scope code */ UCHAR ucMenuScope; /* Menu scope */ UCHAR ucRunMode; /* Run mode */ PSZ pszExecHost; /* Reserved */ PSZ pszMsgAction; /* Reserved */ PSZ pszMsgData; /* Reserved */ UCHAR ucMsgScope; /* Reserved */ BYTE Reserved[WKF_NUM_RESERVEDBYTES]; /* Reserved */ } WKF_ACTION; ═══ Field - pszCommand ═══ pszCommand (PSZ) This field contains the ASCIIZ command or executable name of the action. The command name for an action is specified on the General page of the action's Change Action settings notebook. ═══ Field - pszSrcMask ═══ pszSrcMask (PSZ) This field contains the ASCIIZ names of the types of files that the action can be invoked for. Each type or mask in this string list is delimited by a WKF_LIST_DELIM character. The action source types and masks are specified in the Types page of the action's Change Action settings notebook. ═══ Field - pszTgtMask ═══ pszTgtMask (PSZ) This field contains the ASCIIZ names of the types of files that can be produced by an invocation of the action. Each type or mask in this string list is delimited by a WKF_LIST_DELIM character. The action target types and masks are specified in the Types page of the action's Change Action settings notebook. ═══ Field - pszDllName ═══ pszDllName (PSZ) This field contains the ASCIIZ name of the dynamic link library used to handle the options for the action. The options DLL for an action is specified on the Options page of the action's Change Action settings notebook. ═══ Field - pszDllEntryName ═══ pszDllEntryName (PSZ) This field contains the ASCIIZ name of the entrypoint class in the DLL identified by pszDllName that could be used to handle the options for the action. The options DLL entrypoint for an action is specified on the Options page of the action's Change Action settings notebook. ═══ Field - pszHelpCmd ═══ pszHelpCmd (PSZ) This field contains the ASCIIZ name of the command that displays customized help for the action. The help command name for an action is specified on the Help page of the action's Change Action settings notebook. ═══ Field - pszHelpTopic ═══ pszHelpTopic (PSZ) This field contains the ASCIIZ name of the help topic that provides the customized help for the action. The help topic string for an action is specified on the Help page of the action's Change Action settings notebook. ═══ Field - ucActionType ═══ ucActionType (UCHAR) Currently, this field always contains WKF_ACTIONTYPE_CMD. This field can contain one of the following values: 0x01 WKF_ACTIONTYPE_CMD Indicates that action is specified as a command to execute. 0x02 WKF_ACTIONTYPE_MSG Indicates that the action is specified as a message to route to a registered router client. Note: This action type is not yet supported as of Verson 2.1 of the WorkFrame/2 product. Currently, all actions are processed as commands. ═══ Field - ucActionScope ═══ ucActionScope (UCHAR) This field can contain one of the following values: 0x0001 WKF_ACTIONSCOPE_FILE The action is a file-scoped action (that is, it applies to files). 0x0002 WKF_ACTIONSCOPE_PROJECT The action is a project-scoped action (applying to projects). 0x0003 WKF_ACTIONSCOPE_BOTH The action can apply to both files and projects. The scope of an action is specified on the General page of the action's Change Action settings notebook. ═══ Field - ucMenuScope ═══ ucMenuScope (UCHAR) This field can contain one of the following values: 1 WKF_MENUSCOPE_DETAIL The action is added to a regular popup menu. 2 WKF_MENUSCOPE_SHORT The action is added to an extended popup menu. The menu scope is specified on the General page of the action's Change Action settings notebook. specified on the General ═══ Field - ucRunMode ═══ ucRunMode (UCHAR) This field can contain one of the following values: 1 WKF_RUNMODE_FULLSCREEN The action is started in a full-screen session. 2 WKF_RUNMODE_WINDOW The action is started in a windowed (vio) session. 3 WKF_RUNMODE_MONITOR The action is started in a WorkFrame/2* Monitor window session. 255 WKF_RUNMODE_DEFAULT The action is started in the default run mode. Within the OS/2* system, default mode allows the Shell to establish the session type. The run mode is specified on the General page of the action's Change Action settings notebook. ═══ 20.35. WKF_ACTIONS ═══ WKF_ACTIONS - action list information structure typedef _Packed struct _WKF_ACTIONS { ULONG ulCount; /* Number of entries in the apActions list */ PWKF_ACTION apActions[1]; /* List of action data structures */ } WKF_ACTIONS; ═══ 20.36. WKF_ACTIONENDINFO ═══ WKF_ACTIONENDINFO - WKMF_ACTIONEND message data structure typedef struct _WKF_ACTIONENDINFO { ULONG cb; /* Size of this structure, in bytes */ LHANDLE hActionId; /* Router-assigned action handle */ ULONG cCodes; /* Number of codes available */ ULONG ulRC; /* Action result code */ ULONG ulTC; /* Action termination code */ CHAR szActionName[1]; /* Action name */ } WKF_ACTIONENDINFO; ═══ Field - cCodes ═══ cCodes (ULONG) Indicates whether one, both, or none of the result and termination codes for the ended action are available. The result code is specified in the ulRC member and the termination code is specified in the ulTC member. This member can contain one of the following values: 0 Neither the result code or termination code is available. 1 Only the result code is available. 2 Both the result code and termination code are available. ═══ Field - ulRC ═══ ulRC (ULONG) The result or completion code returned by the ended program. In OS/2*, this value is returned by the DosExecPgm and DosStartSession APIs. If the result code is not available, the cCodes field should be set to zero. ═══ Field - ulTC ═══ ulTC (ULONG) Termination code furnished by the system that describes why the a process ended. The termination code is returned by the DosExecPgm OS/2* API for a synchronous request. If this value is not available, the cCodes field should be updated accordingly. ═══ Field - szActionName[1] ═══ szActionName[1] (CHAR) Name of the ended action. ═══ 20.37. WKF_ACTIONSTARTINFO ═══ WKF_ACTIONSTARTINFO - WKMF_ACTIONSTART message data structure typedef struct _WKF_ACTIONSTARTINFO { ULONG cb; /* Size of this structure, in bytes */ LHANDLE hActionId; /* Router-assigned action handle */ CHAR szActionName[1]; /* Action name */ } WKF_ACTIONSTARTINFO; ═══ Field - szActionName[1] ═══ szActionName[1] (CHAR) Name of the started action. ═══ 20.38. WKF_APPSTARTINFO ═══ WKF_APPSTARTINFO - WKMF_APPSTARTNOTIFY message data structure typedef struct _WKF_APPSTARTINFO { ULONG cb; /* Size of this structure, in bytes */ HAPP happ; /* Application handle */ } WKF_APPSTARTINFO; ═══ Field - happ ═══ happ (HAPP) Application handle assigned by the message router to uniquely identify the running application. ═══ 20.39. WKF_APPTERMINFO ═══ WKF_APPTERMINFO - WKMF_APPTERMNOTIFY message data structure typedef struct _WKF_APPTERMINFO { ULONG cb; /* Size of this structure, in bytes */ HAPP happ; /* Application handle */ ULONG ulReturn; /* Application return code */ } WKF_APPTERMINFO; ═══ Field - happ ═══ happ (HAPP) Application handle assigned by the message router to uniquely identify the terminated application. ═══ Field - ulReturn ═══ ulReturn (ULONG) Return code returned by the application when it terminated. ═══ 20.40. WKF_CHANGEINFO ═══ WKF_CHANGEINFO - WKF_CLIENTCHANGED message data structure typedef struct _WKF_CHANGEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flChanged; /* Changed flag word */ CHAR szParm[1]; /* Name of file changed */ } WKF_CHANGEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field contains a single file name relating to the client component that changed. For example, if the client changed was a base project, this field would contain the name of the project file. ═══ Field - flChanged ═══ flChanged (ULONG) This field flags the components of the client that have changed. It applies only to base projects (that is, clients of type WKF_TYPE_PROJECT). This field is NULL for all other client types. Following are the WorkFrame/2*-defined change flags for base project client types: WKF_PROJECT_DIRECTORY Source directories changed WKF_PROJECT_ACCESSMETHOD Project access method (PAM) changed WKF_PROJECT_TARGETNAME Target program file name changed WKF_PROJECT_MAKEFILE Make file name changed WKF_PROJECT_MASK File masks changed WKF_PROJECT_PROFILE Actions profile changed WKF_PROJECT_TARGETPATH Working directory changed WKF_PROJECT_TARGETPARM Target program parameters changed WKF_PROJECT_TARGETPROMPT Target prompt required flag changed WKF_PROJECT_TARGETTYPE Target run mode changed WKF_PROJECT_MONITOR Monitor options changed WKF_PROJECT_FILEMENU Menu type (regular or extended) for file-scoped actions changed WKF_PROJECT_PROJECTMENU Menu type (regular or extended) for project-scoped actions changed WKF_PROJECT_OPENACTION Default open behavior for non-executable files WKF_PROJECT_EXECACTION Default open behavior for executable files WKF_PROJECT_STANDARD Sets all of the above flags. This flag can be used to flag an unknown change. Change flags may be combined using the bitwise-OR (|) operator. ═══ 20.41. WKF_DELETEINFO ═══ WKF_DELETEINFO - WKFM_CLIENTDELETED message data structure typedef struct _WKF_DELETEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flChanged; /* Reserved */ CHAR szParm[1]; /* Name of deleted file */ } WKF_DELETEINFO; Note: This structure has the same format as the WKF_CHANGEINFO, WKF_MOVEINFO, and WKF_RENAMEINFO structures. ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field contains a single file name relating to the client that was deleted. For example, if the client deleted was a base project, this field would contain the name of its project file. ═══ Field - flChanged ═══ flChanged (ULONG) Reserved value, zero. ═══ 20.42. WKF_ENVIRON ═══ WKF_ENVIRON - environment data structure. typedef _Packed struct _WKF_ENVIRON { PSZ pszEnvName; /* Environment variable name */ PSZ pszEnvStr; /* Environment variable string */ } WKF_ENVIRON; ═══ 20.43. WKF_ENVIRONS ═══ WKF_ENVIRONS - environment list structure. typedef _Packed struct _WKF_ENVIRONS { ULONG ulCount; /* Number of entries in the apEnvirons list */ PWKF_ENVIRON apEnvirons[1]; /* List of environment data structures */ } WKF_ENVIRONS; ═══ 20.44. WKF_ERRORMSGINFO ═══ WKF_ERRORMSGINFO - WKFM_LOGERROR message data structure typedef struct _WKF_ERRORMSGINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG idError; /* Error ID */ BOOL fActivate; /* Activate log flag */ CHAR szText[1]; /* Message text */ } WKF_ERRORMSGINFO; ═══ Field - idError ═══ idError (ULONG) Error message identifier. The identifier may be OS/2-defined or user-defined. Is this the resource file string table entry ID??? ═══ Field - fActivate ═══ fActivate (BOOL) If this flag is set to TRUE, the Action Log will make itself visible when it displays the error message. If this flag is set to FALSE, the error message will still be logged but the Action Log will not be brought to the front of the screen. ═══ Field - szText[1] ═══ szText[1] (CHAR) Error message text to display in the WorkFrame/2* Action Log. ═══ 20.45. WKF_EXECUTEINFO ═══ WKF_EXECUTEINFO - WKFM_EXECUTEACTION message data structure typedef struct _WKF_EXECUTEINFO { ULONG cb; /* Size of this structure, in bytes */ LHANDLE hActionId; /* Router-assigned action handle */ ULONG flOptions; /* WF/2 Monitor options */ CHAR szProjectFile[CCHMAXPATH]; /* Project file name */ CHAR szActionName[WKF_MAX_NAMELEN]; /* Action name */ CHAR szActionClass[WKF_MAX_CLASSLEN]; /* Action class name */ ULONG ulRunMode; /* Program run mode */ ULONG cFiles; /* Number of files listed in the szFiles buffer */ CHAR szFiles[1]; /* Source files list */ } WKF_EXECUTEINFO; ═══ Field - szActionName[WKF_MAX_NAMELEN] ═══ szActionName[WKF_MAX_NAMELEN] (CHAR) The name of the action to execute. Specify NULL to execute the default action for the action class specified in the szActionClass field. ═══ Field - hActionId ═══ hActionId (LHANDLE) This action handle is assigned by the message router to uniquely identify the action to be executed. The message router updates this field for its own internal use. This value is included in the information structures of the WKFM_ACTIONSTART and WKFM_ACTIONEND router messages. ═══ Field - flOptions ═══ flOptions (ULONG) Monitor options flags. This field applies to actions that are to be run in a WorkFrame/2* Monitor window (see ulRunMode). This field can contain one or more of the following flags combined using the bitwise-OR (|) operator: WKF_MTR_AUTOCLOSE Close Monitor if action terminated with no errors WKF_MTR_MINIMIZE Start Monitor minimized WKF_MTR_MULTIPLE Allow multiple, concurrent monitors ═══ Field - ulRunMode ═══ ulRunMode (ULONG) The run mode in which the action is to be executed. This field can contain any one of the following values: WKF_RUNMODE_FULLSCREEN Action is to be started in a full-screen session. WKF_RUNMODE_WINDOW Action is to be started in a windowed (vio) session. WKF_RUNMODE_MONITOR Action is to be started in a WorkFrame/2* Monitor window. WKF_RUNMODE_DEFAULT Action is to be started in default run mode. Within the OS/2* system, default mode allows the Shell to establish the session type. ═══ Field - cFiles ═══ cFiles (ULONG) Number of files listed in the szFiles string list buffer. ═══ Field - szFiles[1] ═══ szFiles[1] (CHAR) A string containing the list of fully-qualified source files for which the action is to be invoked. Each file name should be delimited by a WKF_LIST_DELIM character constant. ═══ 20.46. WKF_FILECHANGEINFO ═══ WKF_FILECHANGEINFO - WKFM_FILECHANGED message data structure typedef struct _WKF_FILECHANGEINFO { ULONG cb; /* Size of this structure, in bytes */ CHAR szParm[1]; /* Project file and changed file names */ } WKF_FILECHANGEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field is a list string that contains the following, each separated by a WKF_LIST_DELIM character constant: Project file name Name of the project file of the project to which the changed file belongs. Changed file name Fully qualified name of the file that was updated or changed. ═══ 20.47. WKF_FILEDELETEINFO ═══ WKF_FILEDELETEINFO - WKFM_FILEDELETED message data structure typedef struct _WKF_FILEDELETEINFO { ULONG cb; /* Size of this structure, in bytes */ CHAR szParm[1]; /* Project file and deleted file names */ } WKF_FILEDELETEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field is a list string that contains the following, each separated by a WKF_LIST_DELIM character constant: Project file name Name of the project file of the project to which the deleted file belonged. Deleted file name Fully qualified name of the file that was deleted. ═══ 20.48. WKF_FILERENAMEINFO ═══ WKF_FILERENAMEINFO - WKFM_FILERENAMED message data structure typedef struct _WKF_FILERENAMEINFO { ULONG cb; /* Size of this structure, in bytes */ CHAR szParm[1]; /* Project file and renamed file names */ } WKF_FILERENAMEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field is a list string that contains the following, each separated by a WKF_LIST_DELIM character constant: Project file name Name of the project file of the project to which the renamed file belongs. Original file name Fully qualified original name of the file that was renamed. New file name Fully qualified new name of the renamed file. ═══ 20.49. WKF_INITIALIZEINFO ═══ WKF_INITIALIZEINFO - Message router client initialization parameter block typedef struct _WKF_INITIALIZEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flConnectType; /* Connection type */ ULONG ulClientType; /* Client type of registering client */ ULONG flTypeInterest; /* Client types interested in */ ULONG flOptions; /* Message router registration options */ CHAR szClientTitle[1]; /* Client title */ } WKF_INITIALIZEINFO; ═══ Field - szClientTitle[1] ═══ szClientTitle[1] (CHAR) Title string of the client. The router uses this string to identify the client when writing an entry to the WorkFrame/2* Action Log on its behalf. ═══ 20.50. WKF_LOGMSGINFO ═══ WKF_LOGMSGINFO - WKFM_LOGMESSAGE message data structure typedef struct _WKF_LOGMSGINFO { ULONG cb; /* Size of this structure, in bytes */ CHAR szText[1]; /* Message text */ } WKF_LOGMSGINFO; ═══ Field - szText[1] ═══ szText[1] (CHAR) Text to display in the WorkFrame/2* Action Log for this client. ═══ 20.51. WKF_MOVEINFO ═══ WKF_MOVEINFO - WKF_CLIENTMOVED message data structure typedef struct _WKF_MOVEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flChanged; /* Reserved */ CHAR szParm[1]; /* Name of moved file */ } WKF_MOVEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field contains three strings: the new client title, the old file name, and the new file name (both fully qualified). None of these strings can be NULL. Take an actions profile object as an example. An actions profile is represented by a single file on disk, under the OS/2 Desktop directory. Its location on the desktop determines its physical path on the disk. Use this field to indicate the new title, the name of the old file, and the name of the new file that represents the actions profile. The client title is the title of the Workplace Shell* object that represents the client, and may or may not be different from its old title. ═══ Field - flChanged ═══ flChanged (ULONG) Reserved value, zero. ═══ 20.52. WKF_RENAMEINFO ═══ WKF_RENAMEINFO - WKF_CLIENTRENAMED message data structure typedef struct _WKF_RENAMEINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG flChanged; /* Reserved */ CHAR szParm[1]; /* Name of file renamed */ } WKF_RENAMEINFO; ═══ Field - szParm[1] ═══ szParm[1] (CHAR) This field contains three strings: the new client title, the old file name, and the new file name, each delimited by a WKF_LIST_DELIM character. None of these strings should be NULL. For example, if the client renamed was a base project, this field would contain its new title, the name of the old project file, and the name of the new project file. The client title is the title of the Workplace Shell* object that represents the client, and may or may not be different from its old title. ═══ Field - flChanged ═══ flChanged (ULONG) Reserved value, zero. ═══ 20.53. WKF_SENDERINFO ═══ WKF_SENDERINFO - Message sender information structure typedef struct _WKF_SENDERINFO { ULONG cb; /* Size of this structure, in bytes */ ULONG ulClientType; /* Client type of sender */ } WKF_SENDERINFO; ═══ 20.54. WKF_TAGPARAM ═══ WKF_TAGPARAM - encoded information to be placed in the item handle of each hwndErrorBox listbox item that contains a valid error message. This data type is used in the Wkf...ParseError API. typedef union _WKF_TAGPARAM { unsigned long tagParam; _Packed struct { USHORT errorLine; /* The line number within the file where the error occurred */ char offset; /* The offset of the error within errorLine, in bytes */ char fileNumber; /* The zero-based index of the file name item within the hwndFilenames listbox */ } sub; } WKF_TAGPARAM; ═══ Field - tagParam ═══ tagParam (unsigned long) If an item in the hwndErrorBox listbox does not contain a valid error message, do not encode any information for that line. This field will contain a zero in the tag/handle field. ═══ Field - fileNumber ═══ fileNumber (char) The zero-based index of the item in the hwndFilenames listbox that corresponds to the name of the source file where the error message occurred. ═══ Field - errorLine ═══ errorLine (USHORT) The number of the line where the error occurs in the file indexed by the fileNumber member. ═══ Field - offset ═══ offset (char) The offset of the error within the line specified by the errorLine member. The offset is in bytes, not characters. Tabs are counted only as one byte. If the offset is not available, zero should be used. ═══ 20.55. WKF_TYPE ═══ WKF_TYPE - type data structure typedef _Packed struct _WKF_TYPE { PSZ pszTypeName; /* Name of the type */ ULONG ulSearchType; /* Pattern or user-defined */ PSZ pszData; /* Type file mask string */ } WKF_TYPE; ═══ Field - pszTypeName ═══ pszTypeName (PSZ) The name of the defined type. ═══ Field - ulSearchType ═══ ulSearchType (ULONG) This field can contain one of the following values: 1 WKF_TYPE_PATTERN Currently, this is the only supported search type. 2 WKF_TYPE_USERDEFINE Currently not supported. ═══ Field - pszData ═══ pszData (PSZ) This field contains the collection of types and file masks that define the type identified by pszTypeName. Each file mask or type is delimited by a WKF_LIST_DELIM character in this list string. ═══ 20.56. WKF_TYPES ═══ WKF_TYPES - type list structure typedef _Packed struct _WKF_TYPES { ULONG ulCount; /* Number of entries in the apTypes list */ PWKF_TYPE apTypes[1]; /* List of type structures */ } WKF_TYPES; ═══ 20.57. WKFBASEPROJECT ═══ WKFBASEPROJECT - base project information structure. The fields in this structure reflect the information specified in the base project Settings notebook, typedef _Packed struct _WKFBASEPROJECT { ULONG cb; /* Size of this structure, in bytes */ CHAR szPAM[CCHMAXPATH]; /* PAM DLL name */ CHAR szDirectory[WKF_MAX_PATHLIST]; /* List of project directories */ CHAR szMask[WKF_MAX_MASKLIST]; /* List of project file masks */ CHAR szTargetName[CCHMAXPATH]; /* Target program file name */ CHAR szTargetParm[WKF_MAX_PARMLIST]; /* Target program parameters */ BOOL fTargetPrompt; /* Target prompt required flag */ ULONG ulTargetType; /* Target program run mode */ ULONG flMonitorFlags; /* Monitor option flags */ CHAR szTargetPath[CCHMAXPATH]; /* Target path name */ CHAR szMakeFile[CCHMAXPATH]; /* Make file name */ CHAR szProfile[CCHMAXPATH]; /* Actions profile file name */ BOOL fFileDetailMenu; /* File-scope menu flag */ BOOL fProjDetailMenu; /* Project-scope menu flag */ CHAR szOpenAction[WKF_MAX_CLASSLEN]; /* Default open action class name */ CHAR szExecAction[WKF_MAX_CLASSLEN]; /* Default execution action class name */ } WKFBASEPROJECT; ═══ Field - szPAM[CCHMAXPATH] ═══ szPAM (CHAR) The fully qualified name of the project access method DLL file specified for the project. ═══ Field - szDirectory[WKF_MAX_PATHLIST] ═══ szDirectory[WKF_MAX_PATHLIST] (CHAR) The string list containing the project source directory path names. Each path name is separated by a WKF_LIST_DELIM character constant. ═══ Field - szMask[WKF_MAX_MASKLIST] ═══ szMask[WKF_MAX_MASKLIST] (CHAR) The project file masks string list. Each file mask string is separated by a WKF_LIST_DELIM character constant. ═══ Field - szTargetName[CCHMAXPATH] ═══ szTargetName[CCHMAXPATH] (CHAR) The unqualified file name of the project's target program. ═══ Field - szTargetParm[WKF_MAX_PARMLIST] ═══ szTargetParm[WKF_MAX_PARMLIST] (CHAR) The parameter string that the target program is to be run with. This field has no value if no parameters were specified or if the target program identified by the szTargetName is not an executable file (for example, a DLL). ═══ Field - fTargetPrompt ═══ fTargetPrompt (BOOL) Flag specifying one of the following: TRUE The user is prompted for a parameter string each time the target program is executed. FALSE No prompt is displayed when the target program is executed. ═══ Field - ulTargetType ═══ ulTargetType (ULONG) Target program run mode. This field can contain any one of the following values: WKF_PJIOPROG_FULLSCREEN Target program is to be run in a full-screen session WKF_PJIOPROG_WINDOW Target program is to be run in a text (vio) window WKF_PJIOPROG_MONITOR Target program output is to be echoed to the WorkFrame/2* Monitor window. ═══ Field - flMonitorFlags ═══ flMonitorFlags (ULONG) Monitor option flags. This field can contain one or more of the following flags, combined using the bitwise-OR (|) operator: WKF_PJIOMON_AUTOCLOSE Monitor is closed if action terminates without error WKF_PJIOMON_MINIMIZE Monitor is started minimized. WKF_PJIOMON_NOMULTIPLE Multiple, concurrent monitors are not allowed. Multiple actions run serially. ═══ Field - szTargetPath[CCHMAXPATH] ═══ szTargetPath[CCHMAXPATH] (CHAR) The fully qualified path name of the project's working directory which is used: o To store the project make file generated by the MakeMake utility o To store files copied from other Workplace Shell* objects o As the current directory when actions are selected on behalf of a project or its parts. ═══ Field - szMakeFile[CCHMAXPATH] ═══ szMakeFile[CCHMAXPATH] (CHAR) The unqualified name of the project's default make file name. ═══ Field - szProfile[CCHMAXPATH] ═══ szProfile[CCHMAXPATH] (CHAR) The fully qualified file name of the actions profile for the project. ═══ Field - fFileDetailMenu ═══ fFileDetailMenu (BOOL) Menu type for file-scoped actions. This field can contain any one of the following values: TRUE File-scoped actions are shown on an extended menu. FALSE File-scoped actions are shown on a regular menu. ═══ Field - fProjDetailMenu ═══ fProjDetailMenu (BOOL) Menu type for project-scoped actions. This field can contain any one of the following values: TRUE Project-scoped actions are shown on an extended menu. FALSE Project-scoped actions are shown on a regular menu. ═══ Field - szOpenAction[WKF_MAX_CLASSLEN] ═══ szOpenAction[WKF_MAX_CLASSLEN] (CHAR) Class name defining the default behavior for non-executable files, for example, EDIT. ═══ Field - szExecAction[WKF_MAX_CLASSLEN] ═══ szExecAction[WKF_MAX_CLASSLEN] (CHAR) Class name defining the default behavior for executable files, for example, RUN. ═══ 20.58. WKFPAM_PART ═══ WKFPAM_PART - represents a single element in the list of project parts passed back to the WKF_ADDFILES callback function. typedef _Packed struct _WKFPAM_PART { ULONG cb; /* Size of this structure, in bytes */ HPOINTER hIcon; /* Handle to a copy of the icon for the file */ PSZ pszSystemData; /* Pointer to a string to display for information */ FILEFINDBUF3 FileFind; /* File information structure */ } WKFPAM_PART; ═══ Field - cb ═══ cb (ULONG) The size of this structure, in bytes, including the FILEFINDBUF3 buffer and other string data, all of which contain variable length strings. ═══ Field - hIcon ═══ hIcon (HPOINTER) A handle to a copy of the icon for the file. This handle does not need to be freed. ═══ Field - pszSystemData ═══ pszSystemData (PSZ) Pointer to a string that contains any special data about the project part that the PAM wishes to display. For example, a library system PAM may display information about the status of a file. The information is displayed in a details view column of the project container. ═══ Field - FileFind ═══ FileFind (FILEFINDBUF3) This structure contains 32-bit (OS/2* level 1) file information, used without extended attributes. Non-OS/2 PAMs should also use this structure to provide the WorkFrame/2* program with the expected project part information. Since the WorkFrame/2* program expects one WKFPAM_PART to represent a single project part, the oNextEntryOffset field of the FILEFINDBUF3 structure should always be set to zero, indicating that there are no other FILEFINDBUF3 structures contained within the WKFPAM_PART structure. ═══ 21. SOM Classes ═══ The WorkFrame/2* program is fully integrated with the OS/2* Workplace Shell* via SOM1, the version of SOM shipped with OS/2. It does not run in a separate WorkFrame/2 shell. As such, it takes full advantage of Workplace Shell object-action techniques by implementing context-sensitive actions and extensive drag-and-drop support. The WorkFrame/2 program inherits features from the Workplace Shell by subclassing the Workplace Shell classes. Following is a diagram illustrating the WorkFrame/2 Workplace Shell class hierarchy. ═══ 22. Persistent Object IDs ═══ This section lists the persistent WorkFrame/2* object IDs that may be useful when creating project and actions profile objects. ┌───────────────────────────────────┬─────────────────────────┐ │ Object │ ID │ ├───────────────────────────────────┼─────────────────────────┤ │WorkFrame/2 main folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Actions Profile folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Information folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Tools folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Samples folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Setup program │ │ ├───────────────────────────────────┼─────────────────────────┤ │Action Log │ │ ├───────────────────────────────────┼─────────────────────────┤ │C/C++ Tools Folder │ │ ├───────────────────────────────────┼─────────────────────────┤ │Sample WF/2 Project Folder (in │ │ │C/C++ Tools Folder) │ │ ├───────────────────────────────────┼─────────────────────────┤ │Default Actions Profile │ │ ├───────────────────────────────────┼─────────────────────────┤ │IBM C/C++ Tools Actions Profile │ │ ├───────────────────────────────────┼─────────────────────────┤ │IBM Toolkit Profile │ │ ├───────────────────────────────────┼─────────────────────────┤ │Sample Actions Profile │ │ ├───────────────────────────────────┼─────────────────────────┤ │CLC Actions Profile │ │ ├───────────────────────────────────┼─────────────────────────┤ │CLC sample project │ │ ├───────────────────────────────────┼─────────────────────────┤ └───────────────────────────────────┴─────────────────────────┘ ═══ ═══ The system object model, or SOM, is the framework on which Workplace Shell* functions that allow the creation and manipulation of objects are based. It establishes a basic inheritance hierarchy for objects in the system and defines the underlying protocols which regulate the relationships between objects. ═══ ═══ Trademark of the IBM Corporation. ═══ ═══ Trademark of the Microsoft Corporation. ═══ ═══ This is an example of a hypertext link. ═══ ═══ The default editor is the default action specified for the EDIT action class. ═══ ═══ Information Presentation Facility ═══ ═══ A resource number is a help window identifier. Each help window within a help (.HLP) file should have a unique resource number that identifies it. ═══ ═══ The application name and data key form the two-level key values that are used to store and retrieve information from project files. An application name key should be unique within an application. Data keys should be unique within the project file. This is similar to the way data is stored and retrieved from OS/2* initialization (.INI) files. For example, the name of working file for an editor called THOR could be stored using THOR for the application key name, and work_file for the data key name. ═══ ═══ Types within the WorkFrame/2* context are similar to OS/2* types (see types in the OS/2 Master Help Index for a full explanation). The types available within the WorkFrame/2 environment are defined on the Types page of the Default Actions Profile notebook. Types simplify the process of specifying the masks of files that can be used as source for an action (source masks), and those that can be produced by the action (target masks). ═══ ═══ A project part is an object that belongs to a WorkFrame/2* project. Currently, the only known kind of project part is a file.