NAME

PowerBuilder:: ORCA - Perl interface to PowerBuilder ORCA API

SYNOPSIS

use PowerBuilder::ORCA qw/:const/;

#open new ORCA session
my $ses=new PowerBuilder::ORCA(['d:\WORK\C\xs\PowerBuilder\ORCA\pbtest.pbl'],
    'd:\WORK\C\xs\PowerBuilder\ORCA\pbtest.pbl',
    'pbtest');

#now, it is possible to carry out manipulations with objects
my $rc=$ses->Export("pbtest.pbl","f_is_dir",PBORCA_FUNCTION,$buf);

my %h;
$ses->EntryInfo("pbtest.pbl","f_db_connect",PBORCA_FUNCTION,\%h);

#close session
$ses->Close();

DESCRIPTION

This module enables to use Powersoft Open Library API (ORCA) from Perl. ORCA is software for accessing the PowerBuilder Library Manager functions that PowerBuilder uses in the Library painter. A perl script can use ORCA to do the same kinds of object and library management that the Library painter interface provides.

ORCA was created for CASE tool vendors as part of the Powersoft CODE (Client/Server Open Development Environment) program. CASE tools needed programmatic access to PowerBuilder libraries to create and modify PowerBuilder objects based on an application design.

To execute programs using ORCA API it is necessary to have pborcNN.dll, which is part professional and enterprise versions of PB, where NN - number of PB version. For example, PowerBuilder version 6 - pborc60.dll.

The detailed description of ideology and functions of ORCA can be found in the documentation on PB ( http://sybooks.sybase.com/onlinebooks/group-pb/adt0650e/orca/ ). It is recommended to read this documentation.

Conformity of ORCA API functions and methods given ORCA.pm:

ORCA API                        ORCA.pm
------------------------------  ------------------
PBORCA_SessionClose             Close
PBORCA_SessionGetError          GetError
PBORCA_SessionOpen              new
PBORCA_SessionSetCurrentAppl    SetAppl
PBORCA_SessionSetLibraryList    SetLibList
PBORCA_LibraryCommentModify     LibCommentModify
PBORCA_LibraryCreate            LibCreate
PBORCA_LibraryDelete            LibDel
PBORCA_LibraryDirectory         LibInfo,LibDir,LibDirList
PBORCA_LibraryEntryCopy         Copy
PBORCA_LibraryEntryDelete       Del
PBORCA_LibraryEntryExport       Export
PBORCA_LibraryEntryInformation  EntryInfo
PBORCA_LibraryEntryMove         Move
PBORCA_CheckOutEntry            CheckOut
PBORCA_CheckInEntry             CheckIn
PBORCA_ListCheckOutEntries      ListCheckOutEntries
PBORCA_CompileEntryImport       Import
PBORCA_CompileEntryImportList   ImportList
PBORCA_CompileEntryRegenerate   Regenerate
PBORCA_ExecutableCreate         ExeCreate
PBORCA_DynamicLibraryCreate     DllCreate
PBORCA_ObjectQueryHierarchy     ObjectQueryHierarchy
PBORCA_ObjectQueryReference     ObjectQueryReference

METHODS

Error handling

The majority of functions return a nonzero error code in a case unsuccessful completion. The error message can be obtained trought GetError function.

Error codes:

Code  Description
----  -----------------------------------
   0  Operation successful
  -1  Invalid parameter list
  -2  Duplicate operation
  -3  Object not found
  -4  Bad library name
  -5  Library list not set
  -6  Library not in library list
  -7  Library I/O error
  -8  Object exists
  -9  Invalid name
 -10  Buffer size is too small
 -11  Compile error
 -12  Link error
 -13  Current application not set
 -14  Object has no ancestors
 -15  Object has no references
 -16  Invalid # of PBDs
 -17  PBD create error
 -18  Source Management error

Initialization

Before the beginning of work it is necessary to specify name of ORCA dll file. Name of dll depends on PB version.

PowerBuilder::ORCA::LoadDll($dll_file);

PowerBuilder::ORCA::LoadDll();

Loads specified dll. If file name specified without path - searches for dll in PATH. If no file specified, function checks environment variable ORCA_DLL. If it exists, loads specified dll. If the variable not exists, searches in PATH for dll of version 9,8,7,6 or 5 and loads the first found. If nothing has helped - dies.

The name of loaded dll is kept in a variable $PowerBuilder::ORCA::ORCA_Dll.

Session management

$ses=new PowerBuilder::ORCA;

$ses=new PowerBuilder::ORCA(\@lib_list);

$ses=new PowerBuilder::ORCA(\@lib_list, $app_pbl, $app_name);

Creates new session object, establishes an ORCA session and returns a handle that you use for subsequent ORCA calls. The second variant of a call also establishes the list of libraries for an ORCA session (see SetLibList). The last variant also establishes the current application object for an ORCA session (see SetAppl).

$rc=$ses->SetLibList($pbl1,$pbl2,...)

You must call SetLibList and SetAppl before calling any ORCA function that compiles or queries objects. Library names should be fully qualified wherever possible.

You can set the current application and library list only once in a session. If you need to change either the library list or current application after it has been set, close the session and open a new session.

ORCA uses the search path to find referenced objects when you regenerate or query objects during an ORCA session. Just like PowerBuilder, ORCA looks through the libraries in the order in which they are specified in the library search path until it finds a referenced object.

You can call the following library management functions and source control functions without setting the library list:

CommentModify
LibCreate
LibDel
LibInfo, LibDir, LibDirList
Copy
Del
Export
EntryInfo
Move
CheckOut
CheckIn

$rc=$ses->SetAppl($pbl,$obj)

You must set the library list before setting the current application.

You must call SetLibList and then SetAppl before calling any ORCA function that compiles or queries objects. The library name should include the full path for the file wherever possible.

You can set the library list and current application only once in a session. If you need to change the current application after it has been set, close the session and open a new session.

The name of pbl should be specified in accuracy as in SetLibList call.

$ses->Close()

Terminates an ORCA session, releases resources.

$errmsg=$ses->GetError()

You can call GetError anytime another ORCA function call results in an error. When an error occurs, functions always return complete error message. If there is no current error, the function will return an empty string.

Manipulations with objects

$rc=$ses->EntryInfo($pbl,$obj,$type,\%hbuf)

Returns the information on object $obj of type $type from library $pbl. The information Includes the comment, the size of the source text, the size of object and date and time of last modification. The information returned in hash %hbuf. Keys of hbuf correspond to the fields of structure PBORCA_ENTRYINFO:

Key         PBORCA_ENTRYINFO field
----------- ---------------------------
Comments    lpszComments
CreateTime  lpszCreateDate, lpszCreateTime
ObjectSize  dwObjectSize
SourceSize  dwSourceSize

Note: SourceSize ORCA returns incorrectly.

You don't need to set the library list or current application before calling this function.

$rc=$ses->Export($pbl,$obj,$type,$buf)

Exports the source code for a PowerBuilder library entry to a buffer $buf.

The comparable function in the Library painter saves the exported source in a text file.

The Library painter includes two header lines in the file. ORCA does not add header lines in its export buffer.

In the buffer, the exported source code includes carriage return (hex 0D) and newline (hex 0A) characters at the end of each display line.

You don't need to set the library list or current application before calling this function.

$rc=$ses->Import($pbl,$obj,$type,$comment,$syntax,\$errbuf)

$rc=$ses->Import($pbl,$obj,$type,$comment,$syntax,\@errbuf)

Imports the source code for a PowerBuilder object into a library and compiles it. If there are compilation errors $rc ==-11 and error messages placed to $errbuf.

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

When errors occur during importing, the object is brought into the library but may need editing. An object with minor errors can be opened in its painter for editing. If the errors are severe enough, the object can fail to open in the painter and you will have to export the object, fix the source code, and import it again.

$rc=$ses->ImportList(\$errbuf,

{
    Library=>'lib1.pbl',
    Name=>'f_func1',
    Type=>PBORCA_FUNCTION,
    Comment=>'comment 1',
    Syntax=>'source_code_of_f_func1'
},
{
    Library=>'lib2.pbl',
    Name=>'another_object_name',
    Type=>PBORCA_type_of_object,
    Comment=>'comment 2',
    Syntax=>'source_code_for_object'
} ...
);

$rc=$ses->ImportList(\@errbuf, ...

Imports the source code for a list of PowerBuilder objects into libraries and compiles them.

If there are compilation errors $rc ==-11 and error messages placed to $errbuf.

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

ImportList is useful for importing several interrelated objects--for example, a window, its menu, and perhaps a user object that it uses.

$rc=$ses->Regenerate($pbl,$obj,$type,\$errbuf)

$rc=$ses->Regenerate($pbl,$obj,$type,\@errbuf)

Compiles an object in a PowerBuilder library.

If there are compilation errors $rc ==-11 and error messages placed to $errbuf. $errbuf can be the reference to a scalar or the reference to an array. In the first case the scalar contains all error messages incorporated into a line. In the second case function return errors as array of hashes, each hash has keys:

Level
MessageNumber
MessageText
ColumnNumber
LineNumber

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

$rc=$ses->ApplicationRebuild($type,\$errbuf)

$rc=$ses->ApplicationRebuild($type,\@errbuf)

Compiles all the objects in the libraries included on the library list. If necessary, the compilation is done in multiple passes to resolve circular dependencies.

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

If you use the compile functions, errors can occur because of the order the objects are compiled. If two objects both refer to each other, then simple compilation will fail. Use PBORCA_ApplicationRebuild to resolve errors due to object dependencies. PBORCA_ApplicationRebuild resolves circular dependencies with multiple passes through the compilation process.

Level
MessageNumber
MessageText
ColumnNumber
LineNumber

$rc=$ses->Copy($src_pbl,$dst_pbl,$obj,$type)

Copies a PowerBuilder library entry from one library to another.

You don't need to set the library list or current application before calling this function.

$rc=$ses->Move($src_pbl,$dst_pbl,$obj,$type)

Moves a PowerBuilder library entry from one library to another.

You don't need to set the library list or current application before calling this function.

$rc=$ses->Del($pbl,$obj,$type)

Deletes a PowerBuilder library file from disk.

You don't need to set the library list or current application before calling this function.

Manipulations with libraries

$rc=$ses->LibInfo($pbl,$comment,$n_obj)

Returns the information on library $pbl. $comment - the comment, $n_obj - number Objects in library.

You don't need to set the library list or current application before calling this function.

$rc=$ses->LibDir($pbl,\@objects);

The array @objects is filled by the information on objects in library $pbl. Each element of @objects - the reference to a hash with the following keys:

Name        a name of object
Type        type of object
Size        the size of object
CreateTime  time of creation of object
Comment     the comment

You don't need to set the library list or current application before calling this function.

$list_ref=$ses->LibDirList($pbl[,$type])

Returns the reference to a array with names of objects of the given type in library $pbl. If the type is not given - returns names of all objects. It is possible to use LibDirList in for loop:

for my $obj_name ( LibDirList('lib1.pbl') ) {
    ...
}

You don't need to set the library list or current application before calling this function.

$rc=$ses->LibCreate($pbl,$comment)

Creates library with a name $pbl.

You don't need to set the library list or current application before calling this function.

$rc=$ses->LibDel($pbl)

Deletes library with a name $pbl.

You don't need to set the library list or current application before calling this function.

$rc=$ses->LibCommentModify($pbl,$new_comment);

Sets the comment for library $pbl.

You don't need to set the library list or current application before calling this function.

VCS interface

$rc=$ses->CheckOut($obj,$type,$master_pbl,$work_pbl,$user_id,$copy)

Checks out a library entry from a master library (the source) to a work library (the destination). $copy - an integer whose value indicates whether to simply change the check-out flags in the libraries or to copy the object to the work library, too. Values are:

0 -- Mark the object as checked out in the master and work libraries, but leave the copy of the object in the work library as is. Do not overwrite it with the copy in the master library

1 -- Mark the object as checked out in the master and work libraries and copy the object from the master library to the work library

$user_id - the version control user ID.

You don't need to set the library list or current application before calling this function.

$rc=$ses->CheckIn($obj,$type,$master_pbl,$work_pbl,$user_id,$move)

Checks in a library entry from a work library (the destination) to a master library (the source). $move - an integer whose value indicates whether to simply change the check-out flags in the libraries or to move the object from the work library to the master library, deleting it from the work library. Values are:

0 -- Clear the check-out status of the object in the master and work libraries, but leave the copy of the object in the master library as is. Do not overwrite it with the copy in the work library and do not delete it from the work library

1 -- Clear the check-out status of the object in the master and work libraries and move the copy in the work library to the master library, deleting it from the work library

$user_id - the version control user ID. The ID must be the same one used to check out the object.

You don't need to set the library list or current application before calling this function.

$rc=$ses->ListCheckOutEntries($pbl,\@storage);

Returns check-out information for objects in a PowerBuilder library.

Each element of array is a hash with the following keys:

LibName     a name of library
Name        a name of object
UserID      a name of the user
Mode        the status (s - source, r - registered, d - distanation)

Hash corresponds to structure PBORCA_CHECKOUT.

You don't need to set the library list or current application before calling this function.

References and inheritance

$rc=$ses->ObjectQueryHierarchy($pbl,$obj,$type,\@storage);

Queries a PowerBuilder object to get a list of the objects in its ancestor hierarchy. Places the result to array @storage. Only windows, menus, and user objects have an ancestor hierarchy that can be queried.

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

$rc=$ses->ObjectQueryReference($pbl,$obj,$type,\@storage);

Queries a PowerBuilder object to get a list of its references to other objects. Places the result to array @storage. Each element of @storage is a hash with following keys:

LibName library name
Name    object name
Type    object type
RefType reference type (o - open, s - simple)

Hash corresponds to structure PBORCA_REFERENCE.

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

Compilation

$rc=$ses->DllCreate($pbl,$pbr,$options);

Creates a PowerBuilder dynamic library (PBD) or PowerBuilder DLL.

Before calling this function, you must have previously set the library list and current application.

If you plan to build an executable in which some of the libraries are dynamic libraries, you must build those dynamic libraries before building the executable.

$options - a long value that indicates which code generation options to apply when building the library (combination of constants described in "Code generation parameters".

$rc=$ses->SetExeInfo({

	CompanyName => 'CompanyName',
	ProductName => 'ProductName',
	Description => 'Description',
	Copyright => 'Copyright',
	FileVersion => '9,9,9,9',
	FileVersionNum => '8,8,8,8',
	ProductVersion => 'ProductVersion',
	ProductVersionNum => '7,7,7,7',
};

Sets the version information, used at creation of the .exe.

$rc=$ses->ExeCreate($exe,$ico,$pbr,\@pbd_flags,$options,\$errors);

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

Creates a PowerBuilder executable with Pcode or machine code. For a machine code executable, you can request several debugging and optimization options. If you are creating a server for a distributed application, you can specify that it be an Open Server executable.

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.

Parameters:

$exe - a name of an executed file (should not exists)
$ico - an icon file
$pbr - a resources (.pbr) file
@pbd_flags - for every pbl in library list:
    0 - to include objects in .exe a file;
    1 - to use already constructed pbd/dll
    The number of elements in a file should correspond to number of
    Libraries in library list
$options - parameters of generation of a code (see L<Code generation parameters>)
$errors - the buffer for errors.

Exported constants

Constans are exported, if tag const specified:

use use PowerBuilder:: ORCA qw/:const/;

Types of objects

PBORCA_APPLICATION
PBORCA_DATAWINDOW
PBORCA_FUNCTION
PBORCA_MENU
PBORCA_PIPELINE
PBORCA_PROJECT
PBORCA_PROXYOBJECT
PBORCA_QUERY
PBORCA_STRUCTURE
PBORCA_USEROBJECT
PBORCA_WINDOW

Code generation parameters

PBORCA_P_CODE
PBORCA_MACHINE_CODE
PBORCA_MACHINE_CODE_NATIVE
PBORCA_MACHINE_CODE_16
PBORCA_P_CODE_16
PBORCA_OPEN_SERVER
PBORCA_TRACE_INFO
PBORCA_ERROR_CONTEXT
PBORCA_MACHINE_CODE_OPT
PBORCA_MACHINE_CODE_OPT_SPEED
PBORCA_MACHINE_CODE_OPT_SPACE
PBORCA_MACHINE_CODE_OPT_NONE

Rebuild type

PBORCA_FULL_REBUILD
PBORCA_INCREMENTAL_REBUILD
PBORCA_MIGRATE

AUTHOR

Ilya Chelpanov, ilya@macro.ru, chelpanov@mail.ru http://i72.by.ru/eng/, http://i72.narod.ru/eng/

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

Error handling

Initialization

Session management

Manipulations with objects

Manipulations with libraries

VCS interface

References and inheritance

Compilation

Exported constants

Types of objects

Code generation parameters

Rebuild type

AUTHOR

SEE ALSO

Module Install Instructions