 

                       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.
