OS/2 Professional

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

/ OS/2 Professional / OS2PRO194.ISO / os2 / info / document / access / accsswps.txt next >

Wrap

Text File | 1993-11-12 | 27.9 KB | 772 lines

ACCESS WPS INFORMATION GENERAL DESCRIPTION AccessWPS is a set of files that allow any PM program to access any WPS method, that can be legally used by a WPS application. AccessWPS has been developed by Carry Associates, 990 Ironwood Court, Marco Island, FL 33937. Our phone number is 813-642-9126 and the fax number is 813-642-1007. We are on Compuserve virtually everyday and our Compuserve ID is 71435,470. If you have any questions or problems with this application, you should contact Carry Associates. Normally, any developer that needs to use one of the methods of a WPS Object must use the SOM Compiler to develop their own WPS Object and then use that Object to actually call one of the WPS Object methods. The reason for this is that WPS runs as a separate process and it is only possible to call one of the WPS methods while running as part of the WPS process. The only way to run as part of the WPS process is to create a WPS Object. AccessWPS solves this problem by creating a general purpose WPS Agent Object that can call any WPS Object method. The Agent Object can be invoked from any PM program by calling an API that is exactly the same as the WPS or SOM method, except that 'Acs' is appended to the front of the method name. For example, _somInit is called via AccessWPS by calling the Acs_somInit API. All of the 'Acs' API's return the exact same return as the corresponding WPS or SOM method, so it is as if it was possible to call the method directly from the PM application. THE PROBLEM WITH POINTERS The biggest with a general purpose WPS Agent concerns the area of pointers to various memory objects. Since WPS runs as a separate process, it cannot access any memory that belongs to the calling process and the calling process cannot access and memory that belongs to the WPS process. Therefore, a mechanism must be provided to address this problem. Any developer using AccessWPS must be aware of 'hidden' pointers that are not obvious because the are hidden by some of the typedefs in the SOM and WPS header files. An example of this is the somId type. If you review the somtypes.h file, you will see that somId is actually a pointer to a pointer to the name of a Class or Object. What this means is that the developer must be careful to place the actual string pointed to in the shared memory area, see discussion below, before calling any of the SOM or WPS methods that use the somId data type. Failure to do this will result in either a NULL return from a method or, and worse, a protection violation in the WPS process. AccessWPS provides two API's, AcsHeapAlloc and AcsHeapFree, which resolve the problem of how to pass memory objects to WPS. These two API's will allocate memory in a dynamically allocated memory pool that is shared between the WPS process and the user's process. This memory pool is allocated during the processing of the AcsInit API and is deleted during the processing of the AcsTerminate API. It is the responsibility of the developer that is using AccessWPS to insure that every pointer passed to WPS is a pointer that was returned by a call to the AcsHeapAlloc API. For example, to pass a string to WPS it is necessary to: 1. Use AcsHeapAlloc to get a memory block that equals the length of the string plus one byte for the null character. 2. Copy the string to the memory allocated via AcsHeapAlloc. The above would also apply to any structure which is passed to WPS or a pointer that is passed and is pointing to an area that will contain returned information, this is done a lot with the _wpQuery type methods. If a pointer to a structure is passed, after copying the structure to the memory block returned by AcsHeapAlloc, and the structure contains a pointer to another memory object or structure, the embedded pointer must also point to a memory block returned via AcsHeapAlloc. Once the API call is complete, it is the responsibility of the developer to release any memory obtained via AcsHeapAlloc via the AcsHeapFree API. This memory should be treated more like stack space that as a heap. In other words, any memory obtained via AcsHeapAlloc should be returned via AcsHeapFree as quickly as possible. The other memory problem concerns pointers that are returned as a result of calling one of the WPS methods. It is possible that the returned value will be a pointer to memory that is allocated to the WPS process. This pointer cannot be used by the PM Application to access the memory object that is being pointed to, since the PM Application cannot access memory that belongs to a different process. The call to the 'Acs' API makes no attempt to resolve this problem. The reason no attempt is made is because it will often be the case that the returned pointer is only going to be used in a subsequent call to another WPS or SOM method, and the PM Application has no need to access the actual memory pointed to. However, there are cases where the PM application needs access to the memory pointed to so an API has been provided, AcsResolvePointer, that will return a pointer to a memory object that can be used by the PM process that is a copy of the same memory in the WPS process. This memory object is allocated via DosAllocMem and it is the responsibility of the callin application to free the memory via DosFreeMem. ********************************************************************** API PROCESSING FLOW AccessWPS actually runs as two DLL's. One of the DLL's, AccssWPS.DLL runs as part of the user's process. The second DLL, AcsAgentDLL, runs as part of the WPS process. Before any WPS or SOM method can be called, the AccessWPS Agent Object must be created via the AcsIniT API call. This API will cause the Agent Class to be registered with WPS, will create an instance of the AccessWPS Object and the Agent Object will open an Object Window which will be used by both DLL's to communicate with each other. In addition, some shared memory areas and semaphores are created by the AccssWPS.DLL and the AcsAgent.DLL will get a pointer to these areas by using their names. Once all processing is completed, the PM Application must issue the AcsTerminate API. This API will destroy the AcsAgent Object, unregister the AccessWPS class and free the shared memory objects and semaphores. The actual processing flow for each WPS or SOM method is as follows: 1. The call of the 'Acs' API actually calls a subroutine for that specific method in the AccssWPS.DLL. 2. The AccssWPS.DLL routine will allocate shared memory to hold the passed parameters and the return and fill in the parameters to be passed to the WPS or SOM method. In addition, any API that requires the SOMClassManager object ID as one of the parameters will check this parameter for a NULL and, if a NULL is found, will substitute the actual SOMClassManager value. This is necessary because it is not possible to access this constant value except when running as part of the WPS process. 3. Once the shared memory is filled, the AccssWPS.DLL file will post a message to the AcsAgent Object Window and then wait on an Event Semaphore. 4. When the AcsAgent.DLL Object Window receives the message, it will call a routine that will actually invoke the requested method and put the value returned from the method, if there is one, in the appropriate place in the shared memory. 5. The AcsAgent.DLL code will then post the Event Semaphore. 6. The posting of the Event Semaphore will cause the AccssWPS.DLL code to fall through the Wait. 7. The AccssWPS.DLL code will save the returned value, if there is any, free the shared memory allocated for this API call and return to the calling PM application. ********************************************************************** INSTALLATION AccessWPS consists of three DLL's, an Import Library, an Include file and a Test program. The three DLL's must be copied into a directory that is in the LIBPATH for the PM Application that will use them. The Import Library, AccssWPS.LIB, must be copied to a directory that will make it available to the linker. This is normally a directory that is in the LIB= entry in the CONFIG.SYS file. The Include file, AccssWPS.H, must be copied into a directory that will make it available to the compiler as an #include file. This is normally on of the directories in the INCLUDE= entry in the CONFIG.SYS file. The Test program, AcsTest.exe, must be copied into a directory that will make it directly executable. This is normally a Directory that is in the PATH= entry in the CONFIG.SYS file. The link of the PM Application must be modified so that the AccssWPS.LIB is included along with the other libraries. Any C source module that calls any of the 'Acs' API's must include the AccssWPS.H include file. In addition, the source module must include the appropriate SOM or WPS #include file and the SOM and/or WPS include file must preceed the AccssWPS.H file. The reason the SOM and/or WPS include files are required is because the 'Acs' API's use the same data types as the actual WPS and SOM methods and these data types are defined in the SOM and WPS include files. There are tests in the AccssWPS.H include file that will only include the AccessWPS API's that correspond to the SOM and/or WPS include files that preceed it. If none of these files preceed the AccssWPS.H file, then none of the API's...except the special ones like AcsInit...will be defined. ********************************************************************** VALIDATING INSTALLATION Once the DLL's and the AcsTest program have been installed, it is suggested that the AcsTest program be run to verify that everything is working correctly. The AcsTest program has no command line parameters and, if everything is working correctly it will: 1. Sound a rising series of tones that indicate the program is starting. 2. A window will appear with a Listbox as the Client area. 3. You will see a series of messages that will appear as the test program goes through it's cycle. There should be no messages that indicate that any of the functions was completed unsuccessfully. 4. There will normally be a delay of a few seconds from the time you see the message that the creation of the Agent Object is starting and the message that it is complete. This is because the AcsAgent and Accsswps DLL's are loaded at this point. 5. Once the Object is created. You will see a line with the Version information on it. If there are any problems, you might be asked for this version information, so it is worht while noting it. 6. Once the version information has been displayed, several lines of internal variable information will be displayed. These are the internal variables for both the Agent Object and the AccssWPS module. This is done primarily to give the developer some idea of the kind of information that is returned when the dump lines are requested. It also provides a sample of how to get the dump information, since the source code for the AcsTest program is now included in the package. 7. To terminate the AcsTest program, simply use the Close entry on the System Menu. You will hear a faliing series of tones as the program terminates indicating that the termination was successful. ********************************************************************** RECOVERY If the AcsTest program will not run, then it is possible that some partial data has been left in the INI files. The purpose of this section is to discuss the places where one might look to manually fix the INI files, so that AccessWPS will work correctly. The intention is to continue to improve AccessWPS so that the initialization and termination routines will be able to handle these conditions automatically. However, a number of different kinds of things could happen to change things at any one time, including a new release of OS/2. This section is starting small, but will be added to as time goes on. The section also assumes that the developer has a tool, such as IniMaint, for searching and editing the INI files. If AcsTest will not run all the way through without an error: 1. The most common problem is an entry in the PM_Workplace:Location Application in the OS2.INI file. If you see a Key Name with <AccessWPSObject>, then there is residual information. You should manually remove this Key Name. Once this is done you should probably remove any invalid WPS entries in the OS2.INI and OS2SYS.INI files by using the Repair function of IniMaint or some similar program. 2. The PM_Objects Application in the OS2SYS.INI file lists all of the registered classes. After AccessWPS has run successfully, there should not be any reference to a Class with the name AcsAgent. If there is, then the Class has not be Deregistered. I have not tried to remove the AcsAgent information manually becuace it has not been necessary. Running AcsTest should remove the information, even if the Creation of the Class and/or the Object is not successful. AcsTest attempt to do the normal termination functions even if the creation functions were not successful and this will normally clean up this entry. 3. If none of the above fix the problem, then the Find capability of IniMaint or some similar program should be used to search both the Key Names and the Key Values of both the OS2.INI and OS2SYS.INI files to look for instances of AccessWPSObject or AcsAgent. If any instances are found, then two things should be done. First, you should notify Carry Associates so that the condition you have found can be incorporated into this section of the documentation. Second, you should, after insuring that you have a backup of your Desktop, manually remove the information. If you are not sure about the effect of the manual removal, it is strongly suggested that you perform a Shutdown and a Reboot to insure that the contents of the INI files and WPS are current with each other. ********************************************************************** SPECIAL AccessWPS API's In order to accomplish all of the necessary functions, there is a set of AccessWPS API's that do not parallel a corresponding SOM or WPS API. They are as follows: BOOL AcsInit() Purpose: Initialize the AccessWPS Agent Class and Object. Returns: 0 - No error non 0 - Error, see error code list Notes: 1. This API must be called as the first API call. If it is not called all of the other API's will return the Not Initialized error code. ********************************************************************** BOOL AcsTerminate() Purpose: Terminate the AccessWPS Agent Class and Object and free the shared memory objects. Returns: 0 - No error non 0 - Error - error code will appear in a message box on screen Notes: 1. There is no way to check to verify that this API has been called before the PM Application terminates. If it is not called, the Agent Object will be left and the shared memory will be left allocated. ********************************************************************** PVOID AcsHeapAlloc(ULONG ulLength) Purpose: To allocate a memory block in the Heap that is shared between the Agent Object's process and the user's process so that both processes can use it. Returns: Valid Pointer - Successful Completion NULL Pointer - Allocation Error - error code will appear in a message box on screen Parameters: ulLength - The size of the memory object requested. ********************************************************************** BOOL AcsHeapFree(PVOID pvMemory) Purpose: To allocate a memory block in the Heap that is shared between the Agent Object's process and the user's process so that both processes can use it. Returns: NO_ERROR - Successful Completion Anthing Else - Error - see Error List Parameters: ********************************************************************** PVOID AcsResolvePointer(PVOID pvWPS, LONG lFixed, BOOL fVariable) Purpose: To make available to the PM process an area of memory that belongs to the WPS process. This is normally a pointer that has been returned from a claa to a WPS or SOM method. Returns: Valid Pointer - Successful Completion NULL Pointer - Error - see AcsReturnError API Parameters: pvWPS - The pointer to the WPS memory area. This is normally a pointer returned from a call to a WPS or SOM method. lFixed - The length of the fixed area pointed to by the pointer above. See the notes below. fVariable - A flag indicating whether or not there is a variable component to the memory object. This must always be a valid C string that is terminated with a NULL character. TRUE - There is a variable portion. FALSE - There is not a variable portion. Notes: 1. Since the WPS memory object could be a structure entry whose length cannot be determined by using the string length API, all memory objects whose length is known, should be requested using the lFixed field to specify the length. 2. If the WPS memory object is a variable length string, then the lFixed value must be zero. 3. Many of the WPS structure entries are compound entries. There is a fixed portion followed by a variable length name field. These pointers should be resolved by passing a non-zero lFixed length and TRUE as the fVariable entry. In this case, it is assumed that the fixed portion is first and is immediately followed by the variable string portion. 4. The returned pointer is one that is allocated using AcsHeapAlloc. It is the responsibility of the calling application to free this memory using AcsHeapFree. If the memory is not freed before the returned pointer is used for a different purpose, the memory will be orphaned until the PM application terminates. The advantage of using AcsHeapAlloc for the returned pointer is that the pointer can then be used to pass the memory on to another WPS method without further processing. Examples: For all of the examples below, it is assumed that the pointer pvNotMine has been returned from a call to a WPS or SOM method. If pvNotMine points to a variable length string: pvReturn = AcsResolvePointer(pvNotMine, 0, TRUE); If pvNotMine points to a fixed length 30 byte structure entry: pvReturn = AcsResolvePointer(pvNotMine, 30, FALSE); If pvNotMine points to a fixed length 40 byte structure entry that is followed by a variable length string: pvReturn = AcsResolvePointer(pvNotMine, 40, TRUE); ********************************************************************** BOOL AcsReturnError() Purpose: Initialize the AccessWPS Agent Class and Object. Returns: 0 - No error non 0 - Error, see error code list Notes: 1. This API is provided so that the Acs Error code can be accessed in those situations where is cannot be returned directly by the Acs API, such as for the AcsResolvePointer API. 2. This API will only return the internal AccessWPS Logic Error Code, there are two other possible error codes, the one returned from a call to a Control Program API, the DOS Error Code, and the error caused by a call to a PM API, the PM Error code. Whenever any error is encountered, all three error codes are preserved. The additional error codes can be obtained by calling the AcsDumpLine API, which will format the error information into normal text lines. ********************************************************************** VOID AcsVersion(PCHAR pchDataLine) Purpose: To get the version of both the AcsAgent.DLL and the AccssWPS.DLL. Parameters: pchDataLine - Pointer to a memory area that is at least 255 bytes long, the returned version information will be placed in this area. ********************************************************************** BOOL AcsDumpLine(PCHAR pchDataLine) Purpose: If an error is returned, this API provides for a method of obtaining a series of Ascii Text lines of data that reflect the contents of the internal variables used by both DLL's. Returns: FALSE - This is the last line of dump data TRUE - There are more lines of dump data, so the same routine needs to be called again Anything Else - Error, see error code list Parameters: pchDataLine - Pointer to a memory area that is at least 255 bytes long, the returned line of dump information will be placed in this area. Notes: 1. Once this routine is called the first time, it should be called over and over until it no longer returns TRUE. If this is not done, then next time the routine is called, it will try to pick up where it left off and the results could be unpredictable. ********************************************************************** INCORRECTLY DOCUMENTED METHODS For the following methods the documentation and the *.h files do not agree. AccessWPS has been implemented to agree with the *.h files. Refer to the AccssWPS.h file for the detailed prototype for these methods. SOMObject methods: Acs_somInitClass - There is an additional parameter passed to this method as the 2nd parameter. It is a zString and is the name of the Class. WPObject methods: Acs_wpCnrRemoveObject - The third parameter is not present in the *.h file. This method is only passed the first two parameters. Acs_wpclsFindObjectFirst - There is an additional parameter, a pointer to a Class List, which is the second parameter which must be passed to the method. Acs_wpAllocMem - The third parameter is a pointer to a long and will contain the return code...I think. WPPalette methods: Acs_wpPaintCell - There is an additional parameter that is passed as the third parameter, a Presentation space to be used for the Paint. Also there is no return from the method, it is defined as VOID. WPFileSystem methods: Acs_wpSetType - There is third parameter, which is a pointer to a FEA2LIST structure. WPFolder methods: Acs_wpPopulate - The second parameter is a pointer to a zero terminated string, not a pointer to a folder object. ********************************************************************** UNPROTOTYPED METHODS The following methods are defined in the Documentation as being available for use. However, they do not have a prototype defined for them in the *.h file, although they are listed in the method table. This normally means they are defined as private methods. Therefore, they are not implemented in AccessWPS. SOMObject methods: _somGetMethodOffset WPPalette methods: _wpShowPalettePointer ********************************************************************** NOT INCLUDED METHODS The following methods are in the documentation and defined in the *.h files. However, they are not included in AccessWPS because they do not appear to be available to be called except by the System or during the processing of another method. If any developer believes there is a need for one of these methods, they can easily be included as part of AccessWPS. SOMObject methods: _somClassReady _somDispatchX _somEnvironmentNew _somPrintf WPObject methods: _wpAddObjectGeneralPage _wpAddObjectWindowPage _wpInsertPopupMenuItems _wpInsertSettingsPage _wpRestoreData _wpRestoreLong _wpRestoreString _wpSaveData _wpSaveLong _wpSaveString WPDataFile methods: _wpAddFileTypePage WPDisk methods: _wpAddDiskDetailsPage WPDesk methods: _wpAddDesktopLockup1Page _wpAddDesktopLockup2Page _wpAddDesktopLockup3Page WPFileSystem methods: _wpAddFile1Page _wpAddFile2Page _wpAddFile3Page _wpAddFileMenuPage _wpAddUserItemsToPopupMenu WPFolder methods: _wpAddFolderView1Page _wpAddFolderView2Page _wpAddFolderView3Page _wpAddFolderIncludePage _wpAddFolderSortPage _wpAddFolderBackgroundPage WPProgram and WPProgramFile methods: _wpAddProgramAssociationPage _wpAddProgramPage _wpAddProgramSessionPage The following methods are not in the documentation but are defined in the *.h files. However, they are not included in AccessWPS because they do not appear to be available to be called except by the System or during the processing of another method. If any developer believes there is a need for one of these methods, they can easily be included as part of AccessWPS. SOMObject methods: _somTotalRegIds _somSetExpectedIds _somUniqueKey _somBeginPersistentIds _somEndPersistentIds _somConstructClass _somGenericApply _somVprintf _somPrefixLevel _somLPrintfsomLPrintf _somGetInstanceToken _somGetMemberToken _somGetInitFunction _somGetRelatedClasses WPFolder methods: _wpRestoreFldrRunObjs _wpStoreFldrRunObjs ********************************************************************** MACRO METHODS The following methods are documented as macros that start with SOM_. However, these methods are actually implemented via a normal method and are implemented in AccessWPS in the same way, that is, as normal Acs_som... methods SOM_Resolve SOM_ResolveNoCheck SOM_ParentResolve SOM_CheckId SOM_CompareIds SOM_StringFromId SOM_IdFromString ********************************************************************** UNDOCUMENTED METHODS The following methods are present in the *.h files, but are not listed in the documentation. They are defined in all of the files, so they can be accessed via AccessWPS. SOMObject methods: Acs_somDataResolve Acs_somNewNoInit Acs_somRenewNoInit Acs_somGetMethodDescriptor Acs_somFindSMethod Acs_somFindSMethodOk WPObject methods: Acs_wpAppendObject Acs_wpAssertObjectMutexSem Acs_wpConfirmObjectTitle Acs_wpCreateAnother Acs_wpFindTaskRec Acs_wpModifyStyle Acs_wpQueryButtonAppearance Acs_wpQueryConcurrentView Acs_wpQueryMinWindow Acs_wpQueryNameClashOptions Acs_wpQueryTrueStyle Acs_wpReleaseObjectMutexSem Acs_wpReplaceObject Acs_wpRequestObjectMutexSem Acs_wpSetButtonAppearance Acs_wpSetConcurrentView Acs_wpSetMinWindow Acs_wpSetTaskRec Acs_wpViewObject Acs_wpclsQueryButtonAppearance Acs_wpclsQueryExtendedCriteria Acs_wpclsQuerySearchInfo WPDataFile methods: Acs_wpQueryAssociatedProgram Acs_wpSetAssociatedFileIcon WPDisk methods: Acs_wpQueryDriveLockStatus Acs_wpEjectDisk Acs_wpLockDrive WPFileSystem methods: Acs_wpConfirmRenameFileWithExt Acs_wpQueryAttr Acs_wpQueryCreation Acs_wpQueryLastAccess Acs_wpQueryLastWrite Acs_wpQueryFileSize Acs_wpQueryEASize Acs_wpQueryRefreshFlags Acs_wpSetAttr Acs_wpSetDateInfo Acs_wpSetFileSizeInfo Acs_wpSetRefreshFlags Acs_wpSetTitleAndRenameFile Acs_wpVerifyUpdateAccess Acs_wpclsQueryObjectFromPath WPFolder methods: Acs_wpContainsFolders Acs_wpFreeIconPosData Acs_wpInitIconPosData Acs_wpQueryFldrSort Acs_wpQueryIconPosition Acs_wpQueryOpenFolders Acs_wpSearchFolder Acs_wpSetFldrSort Acs_wpStoreIconPosData ********************************************************************** AccessWPS ERROR CODES 10101 - Creation of Shared Heap failed. 10102 - Creation of Shared Information Structure failed. 10103 - Agent Object Window Pointer NULL. 10104 - Free of Shared Heap failed. 10105 - Free of Shared Information Structure failed. 10106 - DosAllocMem failed. 10107 - Null pointer passed to AcsResolvePointer. 10108 - Agent Object not active. 10200 - Registration of Agent Class failed. 10201 - Creation of Agent Object failed. 10202 - Removal of Agent Object failed. 10203 - Unable to Post Message to Agent Object Window. 10204 - Error posting or waiting on Semaphore 10205 - Null pointer passed to AcsDumpLine.