Class: cWorkspace

cObject
---cWorkspace

An instance of cWorkspace is automatically created in the cApplication class, so you will rarely need to instantiate an object of this class explicitly. You can obtain the handle of this instance from cApplication's phoWorkspace property.

psWorkspaceWSFile contains the full path name of the workspace (.ws) file.

Typically, you open a Workspace using the cApplication's DoOpenWorkspace method. But, for more control, you can open a Workspace using this class's OpenWorkspace to open a registered Workspace, or OpenWorkspaceFile, to open a non-registered Workspace. If an error occurs opening a Workspace, you can use OpenWorkspaceErrorMessage to retrieve a meaningful description of the error.

Once you have opened a Workspace, you can obtain information about the paths of the Workspace using psAppSrcPath, psBitmapPath, psDataPath, psDdSrcPath, psHelpPath, psIdeSrcPath, psAppHtmlPath and even the system paths psSystemDfPath and psSystemMakePath. As any of these properties can contain multiple paths, you can use the CountOfPaths to return the number of paths contained within them and you can retrieve them individually using PathAtIndex.

When you open a Workspace, the properties of the class are populated with the contents of the WorkspaceFile. For example, psAppSrcPath will contain the contents of the AppSrcPath entry of the Workspace file. However, when the paths are copied, they are converted from relative to absolute paths. The paths are resolved to their absolute names using the value of the Home entry. Home is itself resolved relative to the folder where the file is found. For example, using this file in the "c:\Accounts\Programs" folder:

Home = ..\

AppSrcPath = .\AppSrc

Home would be resolved to the fully qualified path of "c:\Accounts" and placed into the psHome property. It is resolved to "c:\Accounts" as the directory where the file is found is "c:\Accounts\Programs" and Home was set to "..\" Therefore, home was resolved as "c:\Accounts\Programs\..\", which is "c:\Accounts".

The psAppSrcPath property would be set to "c:\Accounts\AppSrc". This is because the AppSrcPath value is resolved relative to Home. As home is "c:\Accounts" and AppSrcPath is ".\AppSrc", the qualified name becomes "c:\Accounts\.\AppSrc". This rule is applied to all the properties containing paths, when they are copied from the Workspace file.

There is one case, however, when the values are not copied from the Workspace file, and that is when the properties already contain a value. This provides great flexibility in manipulating how the Workspace paths are resolved. There are two ways that the properties can contain a value before opening a Workspace. The first is because you have already opened a Workspace and you are changing to another one. If this is the case, you should send DoClearPaths to ensure that all the properties are cleared. The other reason is that you explicitly set their value, so that it would override the values of the Workspace file.

In the following example, the DataPath of the Workspace file is to be ignored and the "test" data path used instead:

Object oApplication is a cApplication

    Procedure OnCreate
        Handle hoWorkspace
 
        Get phoWorkspace to hoWorkspace
        Set psDataPath of hoWorkspace to ".\Data\Test"

        Send DoOpenWorkspace "ABC, Inc.Accounts"
    End_Procedure

End_Object

This example assumes that there is a folder below the Workspace's Data directory called "Test".

In this next example, we go further and read the name of a Workspace file (which may or may not be registered) and its DataPath from the command-line:

Object oApplication is a cApplication

    Procedure OnCreate
        Handle hoWorkspace hoCmdLine
        Integer eOpened
        String sWorkspace sDataPath sError
 
        // default value in case no workspace name is passed
        Move "ABC, Inc.Accounts" to sWorkspace

        Get phoWorkspace to hoWorkspace
        Get phoCommandLine to hoCmdLine
 
        If (CountOfArgs(hoCmdLine) >=1) Begin // read the Workspace name
            Get Argument of hoCmdLine 1 to sWorkspace
        End

        If (CountOfArgs(hoCmdLine) >=2) Begin // read the DataPath name
            Get Argument of hoCmdLine 2 to sDataPath
            Set psDataPath of hoWorkspace to sDataPath
        End

        Get OpenWorkspaceFile of hoWorkspace sWorkspace to eOpened
        If (eOpened <> wsWorkspaceOpened) Begin
            Get OpenWorkspaceErrorMessage of hoWorkspace eOpened to sError
            Send Stop_Box sError "Error Opening Workspace"
            Abort
        End
    End_Procedure

End_Object

Notice that in this example, we used the OpenWorkspaceFile function. This ensures that as long as the Workspace file exists, it doesn't need to be registered. This is a very useful technique. You could have multiple Workspace files that have different entries. For example, you could have two files, Accounts.Real and Accounts.Test. The Accounts.Test file could have its DataPath pointing to test data. In your program, you could decide which one to use and just open it dynamically.

cApplication