Developing and deploying in a multiplatform environment

PowerBuilder makes it easy to share files and do part of the
development work on one platform and part on another. This section
discusses file-sharing considerations, both during development and
for a deployed application.

Moving and sharing files across platforms

You can move PowerBuilder files and resources to any platform.
You don’t need to convert text files on most platforms.
Depending on the PowerBuilder versions on each platform, you may not
need to regenerate libraries.

The following table summarizes what kinds of files must be
modified when you are developing or deploying files across multiple
platforms. These rules apply to all platforms.

File type	Modifications required
PBL	None if PowerBuilder version numbers are the same
Image	None if file type is supported
Text	None
Initialization (INI)	Line endings and content may need to be modified
Executable (EXE)	Must be rebuilt
Machine-code dynamic library	Must be rebuilt
PBD	None if PowerBuilder version numbers are the same

The following sections describe each file type in more detail.

When you are developing a multiplatform application, developers
on different platforms can all access files that are stored on shared
drives. If the PowerBuilder version numbers are the same, you don’t
need to move the files to a particular platform or perform any conversions
to use them.

PowerBuilder libraries

PowerBuilder libraries (PBLs) are the files that hold the objects
of your application. When you are developing on multiple platforms,
you can move a PBL developed on one platform to the other platforms,
or you can place the PBL in a shared location accessible from all
platforms.

You can move or share PBLs among all supported platforms,
with these restrictions:

• If the PowerBuilder version
  is the same on the platform that created the PBL and on the platforms
  that use the PBL (for example, all are Version 7.0; none
  are 6.0), you can use the PBLs with no change, sharing the same file
  among platforms. You don’t need to regenerate the objects
  in the library.
• If the PowerBuilder versions are different, you will
  need to create a copy of the PBL for the different platforms and
  regenerate the objects. You cannot share files when the PowerBuilder versions
  are different.

Although you may be able to use PBLs on other platforms without
regenerating the objects, it is a good idea to regenerate anyway
(unless all developers must work from a single set of shared files).

Text files

Each of the platforms that PowerBuilder supports uses different
line endings (also called line terminators) for text files. In most
cases, PowerBuilder recognizes all line endings as valid and can read
all text files correctly. You do not need to convert Windows files
for PowerBuilder to access them on UNIX. Nor do you need to convert
UNIX files to access them on Windows.

For information about handling text files in PowerBuilder for
Unicode, “File handling in PowerBuilder for
Unicode”.

Text files used by PowerBuilder include object source code exported
from the Library painter, files saved in the text editor, and files
read with the FileRead function.

Although initialization files (also called INI or preference
files) are text files, PowerBuilder uses different function calls
to access them. They are not compatible across all platforms. See “Initialization files”.

Saving text files–whatline endings to use

The Library painter has a preference variable that controls
what line endings are written. When you use the FileRead and FileWrite
functions in scripts, the way the file is opened controls the handling
of line endings.

Library painter

When reading a text file in the Library painter, PowerBuilder detects
the characters used for line endings and reads the file correctly.
When writing text files, PowerBuilder writes the file using line endings
appropriate for the current platform unless you specify otherwise.

In the PowerBuilder initialization file, you can set the LibraryExportFileType preference
variable to tell PowerBuilder the type of line endings to use when PowerBuilder exports
object source code from the Library painter.

The values you can specify for LibraryExportFileType are:

Value	Meaning
0	Use the default line endings for the current platform (default behavior)
1	Use DOS line endings (CR/LF)
2	Use Macintosh line endings (CR only)
3	Use UNIX line endings (LF only)

Your PowerBuilder initialization file might include lines like
these:

FileRead and FileWrite functions

The way the FileRead and FileWrite functions handle line endings
depends on whether the file was opened in line mode or stream mode.

Function	Mode	Result
FileRead	Line	Returns one line at a time. Line-ending characters are ignored
Stream	Returns a block of raw data. It is up to you to parse the data and detect the type of line endings, if any
FileWrite	Line	Writes a block of data. You control the type of line endings, if any, by including the appropriate characters in the data
Stream	Writes one line at a time, ending each line with the line-ending characters appropriate to the current platform. If you are appending data to an existing text file, these line endings may not match the line endings in the text file–FileWrite always uses the line endings of the current platform

Example of using different line endings

In a script, you might use code like the following to control
which line endings to write. In this example, the user selected
a target platform by choosing a radio button whose script set the
instance variable is_end.

Instance variables for the window are:

The script for the UNIX radio button sets is_end
to LF (~n):

The script for the Windows radio button sets is_end
to CR/LF (~r~n):

The script that writes the file opens the file in stream mode
and writes each line from an array of strings (the instance variable
is_lines_of_data[]).
After each line, it writes the value in is_end. The filename
is stored in the instance variable is_filename:

Initialization files

PowerBuilder cannot
access an initialization
file unless it has been converted to the native line endings for
the current platform. To share the information in an initialization
file, you must make a copy of the file and convert it using an appropriate
utility.

Initialization files in the development environment

The PowerBuilder initialization file should never be shared
with another user on the same or a different platform. In addition,
because it contains configuration information in the form of filenames
and paths, the PowerBuilder initialization file on one platform is
not meaningful when PowerBuilder is run on another platform.

Name of the PowerBuilder initialization file

On Windows, the PowerBuilder initialization file is called PB.INI.
On UNIX, the file is called .pb.ini. Scripts that run on all platforms
and access this file will need conditional code to specify the correct
filename.

See “Executing code for
specific platforms “.

Reusing or sharing database profiles

Database profiles, which are also stored in the PowerBuilder initialization
file, are usable on any platform. If you have created database profiles
on one platform, you can transfer them to another platform by converting
the line endings in the PowerBuilder initialization file from the
source platform and then cutting and pasting the database profile
sections into the PowerBuilder initialization file being used on the
target platform. You can use a text conversion tool to open the
file and save it in the native format.

Several users can read profiles from a shared initialization
file, but the initialization file must have the appropriate line
endings for the platform being used.

For information, see the chapter on managing
database connections in Connecting to Your Database
.

Initialization files for the application

Your deployed application needs its own initialization files.

Initialization files are one way to store preferences and
default settings. They are text files, which makes them portable.
Because PowerBuilder makes it easy to access information in Windows-style
initialization files, this format is a good one to use even though
it is unfamiliar to UNIX users.

When you move your application’s initialization file
from one platform to another, you need to convert line endings,
as described in “Text files”.

System registry Although Windows uses a system registry for application settings,
you should not use the registry for cross-platform applications.
There is no UNIX registry.

Application access to initialization files

The functions ProfileString, ProfileInt, and SetProfileString
allow you to get and set values in initialization files. To simplify
the scripts that call these functions, use names for the initialization
files that are valid on all your target platforms. When you deploy
the application, put the files where the application can find them
so you don’t have to specify a path with the filename.

Don’t rely on system preferences files Although you can use ProfileString and related functions to
access the Windows preferences file WIN.INI and the .WindU file
on UNIX, if you have to store system information for your application,
make sure you put it in your own preferences file. Don’t
rely on system settings that may not be available on all target
platforms.

If you must retrieve values from system initialization files
or if you need to specify paths when you call the Profile functions
to access initialization files, you can use the GetEnvironment function
and write code specific to each platform.
See “Executing code for
specific platforms “.

Executable files

The executable file that you deploy with your application
contains platform-specific information. It must be built specifically
for each platform. You cannot move an executable built for Windows
to UNIX, nor an executable built for Solaris to HP-UX.

Whether you want to build a Pcode or compiled code executable,
you use the PBLs that you’ve already developed (locally
or on another platform) to build the executable file.

Machine code dynamic libraries

Machine code dynamic libraries or shared libraries are platform-specific. Before
you deploy your application, you must:

• Move your PBLs to
  the target platform
• Regenerate all objects
• Build the dynamic libraries on the target platform

PBD files

For best performance, you should move your PBLs to the target
platform, regenerate all objects, and build PowerBuilder dynamic library
(PBD) files on the target platform.

Same version

If the PowerBuilder version is the same on all platforms (for
example, they are all 7.0), then the PBD files are compatible
across platforms. You can use PBLs to build PBDs on any platform
and deploy the resulting files on all platforms. You can also place
the PBDs on a file server that all your users can access. However,
it is still a good idea to regenerate objects and build PBDs on
each target platform, especially if you encounter problems.

Different versions

If the PowerBuilder versions are different (they are not all 7.0),
you must
move the PBLs to the target platform,
regenerate, and rebuild the PBD files.

How your applicationfinds external files

PowerBuilder uses search paths to find external files when you
do not specify a full path to the file. External files include initialization
or preferences files, files opened with the FileOpen function, program
names specified in the Run function, Help files, and image files
for PictureButton controls, toolbar buttons, and so forth.

When you specify a path

If you specify a full path for a file, PowerBuilder will find
the file in the specified directory or folder. It will
not use the search paths described here
. To keep your
application’s configuration flexible, you generally do
not want to specify a path when you name a file, because the user’s
system configuration will probably differ from your own setup.

Using PBR files

If you create a PowerBuilder Resource (PBR) file for your application
that lists external files used in your application, the files become
part of your executable or its dynamic libraries. They are no longer
external files and the paths described here are not relevant.

Finding files

The search order for files is different on each platform.

On Windows

On Windows, PowerBuilder searches for files in the following
locations in the order shown here:

1. The current (working) directory.
2. The WINDOWS or WINNT directory.
3. The WINDOWS or WINNT System or System32 directory.
4. All directories on the DOS path.

On UNIX

On UNIX, PowerBuilder searches for files in the following locations
in the order shown here:

1. The current (working)
   directory.
2. The user’s home directory.
3. The directories in the user’s PATH environment
   variable.

---