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 );

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;

1	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;

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

1 2	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

1 2	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-&gt;hORCASession,
   pszExecFile, pszIconFile, pszResourceFile,
   fpLinkProc, lpUserData,
   (INT FAR *) iPBDFlags, 4, lBuildOptions, NULL );

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

Document get from Powerbuilder help

Thank you for watching.

Powerbuilder Documentation 2017

August 20, 2023

Was this article helpful?

Connection Information

PBORCA_ExecutableCreate – PB Docs 2017

PBORCA_ExecutableCreate

My Website Links