HomePowerBuilderAppeon Documentation Center

PBORCA_ExecutableCreate

Description

Creates a PowerBuilder executable with Pcode or machine code. For a machine code executable, you can request several debugging and optimization options.

The ORCA library list is used to create the application. You can specify which of the libraries have already been built as PBDs or DLLs and which will be built into the executable file.

Syntax

INT PBORCA_ExecutableCreate ( HPBORCA hORCASession, 
   LPTSTR lpszExeName, 
   LPTSTR lpszIconName, 
   LPTSTR lpszPBRName, 
   PBORCA_LNKPROC pLinkErrProc, 
   LPVOID pUserData, 
   INT FAR *iPBDFlags, 
   INT iNumberOfPBDFlags, 
   LONG lFlags, 
   LPVOID pbcPara = NULL );

Argument

Description

hORCASession

Handle to previously established ORCA session.

lpszExeName

Pointer to a string whose value is the name of the executable file to be created.

lpszIconName

Pointer to a string whose value is the name of an icon file. The icon file must already exist.

lpszPBRName

Pointer to a string whose value is the name of a PowerBuilder resource file. The resource file you name must already exist. If the application has no resource file, specify 0 for the pointer.

pLinkErrProc

Pointer to the PBORCA_ExecutableCreate callback function. The callback function is called for each link error that occurs.

The information ORCA passes to the callback function is the message text, stored in a structure of type PBORCA_LINKERR.

If you don't want to use a callback function, set pLinkErrProc to 0.

pUserData

Pointer to user data to be passed to the PBORCA_ExecutableCreate callback function.

The user data typically includes the buffer or a pointer to the buffer in which the callback function formats the directory information as well as information about the size of the buffer.

If you are not using a callback function, set pUserData to 0.

iPBDFlags

Pointer to an array of integers that indicate which libraries on the ORCA session's library list should be built into PowerBuilder dynamic libraries (PBDs). Each array element corresponds to a library in the library list. Flag values are:

  • 0 -- Include the library's objects in the executable file

  • 1 -- The library is already a PBD or PowerBuilder DLL and its objects should not be included in the executable

iNumberOfPBDFlags

The number of elements in the array iPBDFlags, which should be the same as the number of libraries on ORCA's library list.

lFlags

A long value whose value indicates which code generation options to apply when building the executable.

Setting lFlags to 0 generates a native Pcode executable. Additional settings for machine code are described in Usage below.

Setting lFlags to PBORCA_X64 generates a 64-bit executable.

pbcPara

Reserved for internal use. Always set pbcPara to NULL.


Return value

INT. Typical return codes are:

Return code

Description

0 PBORCA_OK

Operation successful

-1 PBORCA_INVALIDPARMS

Invalid parameter list

-5 PBORCA_LIBLISTNOTSET

Library list not set

-12 PBORCA_LINKERROR

Link error

-13 PBORCA_CURRAPPLNOTSET

Current application not set

Usage

You must set the library list and current Application object before calling this function.

For more information about various options for building executables, see the PowerBuilder User's Guide.

Libraries used in the executable

The executable being built incorporates the objects in the libraries on ORCA's library list. The library list must be set by calling PBORCA_SessionSetLibraryList before creating an executable.

The iPBDFlags argument lets you specify which libraries are PBDs and which will be built into the executable file. In the iPBDFlags array, each integer is associated with a library on ORCA's library list. When you set an integer to 1, the objects in the corresponding library are already built into a PBD file (if you are generating Pcode) or a PowerBuilder DLL (if you are generating machine code). Objects in libraries whose integer flag is set to 0 will be built into the main executable file.

Before you call PBORCA_ExecutableCreate, you must call PBORCA_DynamicLibraryCreate to create the PBDs or DLLs that you identify in the iPBDFlags array.

Setting code generation options

In the lFlags argument, you can set various machine code generation options by setting individual bits. The following table shows what each defined bit means in the long value and what constants to use in a bitwise OR expression to set the option. Bits not listed are reserved.

Bit

Value and meaning

Constant to include in ORed expression

0

0 = Pcode

1 = Machine code

To get machine code, use PBORCA_MACHINE_CODE or PBORCA_MACHINE_CODE_NATIVE

1

0 = Native code

1 = 16-bit code

To get 16-bit machine code, use PBORCA_MACHINE_CODE and PBORCA_MACHINE_CODE_16

To get 16-bit Pcode, use PBORCA_P_CODE_16

Not supported after PowerBuilder 7

PowerBuilder no longer supports the Windows 3.x 16-bit platform.

2

0 = No Open Server

1 = Open Server

To build an Open Server executable, use PBORCA_OPEN_SERVER

Not supported after PowerBuilder 5

The OpenClientServer driver was no longer supported after PowerBuilder 5. Therefore, the Open Server executable option is no longer supported.

4

0 = No trace information

1 = Trace information

To get trace information, use PBORCA_TRACE_INFO

5

0 = No error context

1 = Error context

To get error context information, use PBORCA_ERROR_CONTEXT

Error context provides the script name and line number of an error.

8

0 = No optimization

1 = Optimization

See Bit 9

9

0 = Optimize for speed

1 = Optimize for space

To optimize the executable for speed, use PBORCA_MACHINE_CODE_OPT or PBORCA_MACHINE_CODE_OPT_SPEED

To optimize the executable for space, use PBORCA_MACHINE_CODE_OPT and PBORCA_MACHINE_CODE_OPT_SPACE

10

0 = Old style visual controls

1 = New style visual controls (XP)

PBORCA_NEW_VISUAL_STYLE_CONTROLS

12

1 = PocketBuilder desktop

PBORCA_PK_DESKTOP (Obsolete)

13

1 = PocketBuilder ARM

PBORCA_PK_PPCARM (Obsolete)

14

1 = PocketBuilder EM86

PBORCA_PK_PPCEM86 (Obsolete)

15

1 = PocketBuilder X86

PBORCA_PK_PPCX86 (Obsolete)

16

1 = PocketBuilder Smartphone ARM

PBORCA_PK_SPHONEARM (Obsolete)

17

1 = PocketBuilder Smartphone X86

PBORCA_PK_SPHONEX86 (Obsolete)

To generate Pcode, lFlags must be 0. The other bits are not relevant: 

lFlags = PBORCA_P_CODE;

To set the lFlags argument for various machine-code options, the bit flag constants are ORed together to get the combination you want: 

lFlags = PBORCA_MACHINE_CODE |
      PBORCA_MACHINE_CODE_OPT |
      PBORCA_MACHINE_CODE_OPT_SPACE;

Constants are defined in PBORCA.H for typical option combinations. They are:

PBORCA_MACHINE_DEFAULT

Meaning native machine code optimized for speed

Equivalent to:

PBORCA_MACHINE_CODE |
         PBORCA_MACHINE_CODE_OPT_SPEED

PBORCA_MACHINE_DEBUG

Meaning native machine code with trace information and error context information

Equivalent to:

PBORCA_MACHINE_CODE | PBORCA_TRACE_INFO |
         PBORCA_ERROR_CONTEXT

eClobber setting

If the executable file already exists in the file system, the current setting of the eClobber property in the ORCA configuration block (that you set with a PBORCA_ConfigureSession call) determines whether PBORCA_ExecutableCreate succeeds or fails.

Current eClobber setting

PBORCA_ExecutableCreate

PBORCA_NOCLOBBER or PBORCA_CLOBBER_DECIDED_BY_SYSTEM

Fails when an executable file already exists in the file system, regardless of the file attribute settings

PBORCA_CLOBBER

Succeeds when the existing executable file has read-write attributes; fails when the executable file has read-only attributes

PBORCA_CLOBBER_ALWAYS

Succeeds regardless of the file attribute settings of an existing executable file


Examples

This example builds a native machine code executable optimized for speed using ORCA's library list and current application. Suppose that the current ORCA session has a library list with four entries. The example generates DLLs for the last two libraries.

The callback function is called LinkErrors, and lpUserData points to an empty buffer to be populated by the callback function: 

LPTSTR pszExecFile;
LPTSTR pszIconFile;
LPTSTR pszResourceFile;
int iPBDFlags[4];
long lBuildOptions;
int rtn;
 
fpLinkProc = (PBORCA_LNKPROC) LinkProc;
// specify file names
pszExecFile = _TEXT("c:\\app\\process.exe");
pszIconFile = _TEXT("c:\\app\\process.ico");
pszResourceFile = _TEXT("c:\\app\\process.pbr");
 
iPBDFlags[0] = 0;
iPBDFlags[1] = 0;
iPBDFlags[2] = 1;
iPBDFlags[3] = 1;
 
lBuildOptions = PBORCA_MACHINE_CODE_NATIVE |
   PBORCA_MACHINE_CODE_OPT_SPEED;
 
// create executable
rtn = PBORCA_ExecutableCreate(
   lpORCA_Info->hORCASession,
   pszExecFile, pszIconFile, pszResourceFile,
   fpLinkProc, lpUserData,
   (INT FAR *) iPBDFlags, 4, lBuildOptions, NULL );

For more information about setting up the data buffer for the callback, see Content of a callback function and the example for PBORCA_LibraryDirectory.

In these examples, session information is saved in the data structure ORCA_Info, shown in About the examples.

See also

PBORCA_ConfigureSession

PBORCA_DynamicLibraryCreate

Prev  Up  Next
PBORCA_DynamicLibraryCreate  Home  PBORCA_LibraryCommentModify