Opens a window, connects to a scanner, camera, or GPS device, or opens a file and selects its access mode.
For windows Open displays a window and makes all its properties and controls available to scripts.
To |
Use |
|---|---|
Open an instance of a particular window datatype |
|
Allow the application to select the window’s datatype when the script is executed |
For BarcodeScanner and BiometricScanner objects Open loads scanner DLLs and connects to scanner firmware.
To |
Use |
|---|---|
Connect to scanner firmware |
For GPS or SerialGPS objects Open opens a communications channel or provides raw data for use by a GPS object.
To |
Use |
|---|---|
For the GPS base class |
|
For the SerialGPS object |
For other objects Open opens a file and selects its access mode.
To |
Use |
|---|---|
Open a communications channel or initialize a Camera object with a set of raw data |
|
Open a Short Message Service (SMS) session |
|
Open a file for reading or writing with the FileDirect object |
|
Open a trace file |
Opens a window object of a known datatype. Open displays the window and makes all its properties and controls available to scripts.
Window objects
Open ( windowvar {, parent } )
Argument |
Description |
|---|---|
windowvar |
The name of the window you want to display. You can specify a window object defined in the Window painter (which is a window datatype) or a variable of the desired window datatype. Open places a reference to the opened window in windowvar. |
parent (child and pop-up windows only) (optional) |
The window you want make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, Open returns null.
You must open a window before you can access the properties of the window. If you access the window’s properties before you open it, an execution error will occur.
To reference an open window in scripts, use windowvar.
Calling Open twice
If you call Syntax 1 of the Open function
twice for the same window, PocketBuilder activates the window twice;
it does not open two instances of the window.
To open an array of windows where each window has different datatype, use Syntax 2 of Open.
Generally, if you are opening a child or a pop-up window and specify parent, the window identified by parent is the parent of the opened window (windowname or windowvar). When a parent window is closed, all its child and pop-up windows are closed too.
Mouse behavior and response windows
Controls capture the mouse or stylus action in order to perform
certain operations. For instance, CommandButtons capture during
mouse clicks, edit controls capture for text selection, and scroll
bars capture during scrolling. If a response window is opened while
the mouse is captured, unexpected results can occur.
Because a response window grabs focus, you should not open it when focus is changing, such as in a LoseFocus event.
This statement opens an instance of a window named w_employee:
Open(w_employee)
The following statements open an instance of a window of the type w_employee:
w_employee w_to_open
Open(w_to_open)
The following code opens an instance of a window of the type child named cw_data and makes w_employee the parent:
child cw_data
Open(cw_data, w_employee)
The following code opens two windows of type w_emp:
w_emp w_e1, w_e2
Open(w_e1)
Open(w_e2)
Opens a window object when you do not know its datatype until the application is running. Open displays the window and makes all its properties and controls available to scripts.
Window objects
Open ( windowvar, windowtype {, parent } )
Argument |
Description |
|---|---|
windowvar |
A window variable, usually of datatype window. Open places a reference to the opened window in windowvar. |
windowtype |
A string whose value is the datatype of the window you want to open. The datatype of windowtype must be the same or a descendant of windowvar. |
parent (child and pop-up windows only) (optional) |
The window you want to make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, Open returns null.
You must open a window before you can access the properties of the window. If you access the window’s properties before you open it, an execution error will occur.
To reference an open window in scripts, use windowvar.
The window object specified in windowtype must be the same datatype as windowvar (the datatype includes datatypes inherited from it). The datatype of windowvar is usually window, from which all windows are inherited, but it can be any ancestor of windowtype. If it is not the same type, an execution error will occur.
Use this syntax to open an array of windows when each window in the array will have a different datatype. See the last example, in which the window datatypes are stored in one array and are used for the windowtype argument when each window in another array is opened.
Considerations when specifying a window type
When you use Syntax 2, PocketBuilder opens an instance of
a window of the datatype specified in windowtype and
places a reference to this instance in the variable windowvar.
If windowtype is a descendent window, you can only reference properties, events, functions, or structures that are part of the definition of windowvar. For example, if a user event is declared for windowtype, you cannot reference it.
The object specified in windowtype is not automatically included in your executable application. To include it, you must save it in a PKD file (PocketBuilder dynamic library) that you deliver with your application.
For information about the parent of an opened window, see Syntax 1 For windows of a known datatype.
This example opens a window of the type specified in the string s_w_name and stores the reference to the window in the variable w_to_open. The SELECT statement retrieves data specifying the window type from the database and stores it in s_w_name:
window w_to_open
string s_w_name
SELECT next_window INTO : s_w_name FROM routing_table
WHERE... ;
Open(w_to_open, s_w_name)
This example opens an array of ten windows of the type specified in the string is_w_emp1 and assigns a title to each window in the array. The string is_w_emp1 is an instance variable whose value is a window type:
integer n
window win_array[10]
FOR n = 1 to 10
Open(win_array[n], is_w_emp1)
win_array[n].title = "Window " + string(n)
NEXT
The following statements open four windows. The type of each window is stored in the array w_stock_type. The window reference from the Open function is assigned to elements in the array w_stock_win:
window w_stock_win[ ]
string w_stock_type[4]
w_stock_type[1] = "w_stock_wine"
w_stock_type[2] = "w_stock_scotch"
w_stock_type[3] = "w_stock_beer"
w_stock_type[4] = "w_stock_soda"
FOR n = 1 to 4
Open(w_stock_win[n], w_stock_type[n])
NEXT
Loads DLLs and connects to scanner firmware.
BarcodeScanner and BiometricScanner objects
Integer scanner.Open ( )
Argument |
Description |
|---|---|
scanner |
The scanner object that you want to open |
Integer. Returns 1 for success or one of the following negative values if an error occurs:
This is typically the first method to call after creation of a scanner object.
The following example loads scanner DLLs and connects to the scanner device firmware:
li_rtn = l_scanner.Open()
Opens an ANSI text file containing NMEA sentences for a GPS object and reads the contents into a buffer.
GPS objects
GPSname.Open ( { rawdatafile } )
Argument |
Description |
|---|---|
GPSname |
Name of the GPS object. |
rawdatafile |
A string for an ASCII text file containing raw data in NMEA-0183 format to be used by the GPS object. |
Integer. Returns 1 for success and a negative number for any error. The following is a list of possible error codes and their meanings:
-10 Invalid object. Could occur if the GPS object instance is corrupted.
-11 No RawData. This error is generated when the ConfigParams property is empty and Open is called without a file name argument.
-12 Invalid File. This error is generated on an Open call containing a file name argument when the file does not exist or cannot be opened successfully.
-15 Read Failure. This error is generated on an Open call containing a file name argument when the file cannot be read.
-18 Already Open. An Open request was issued and the object is already open.
Use this function to populate the fields of the GPS base object.
The optional rawdatafile argument is used when the data to be loaded resides in an ANSI text file. The entire data file is read into a buffer for use by the GetFix, GetHeading, and GetSatellitesInView routines. Raw data files must be ANSI text.
The following lines create a GPS object, retrieve information about the current position fix, and test the validity of the GPSFix object:
Gps myGPS GPSFix myFix
Integer rc
String errmsg
MyGPS = CREATE GPS
rc = myGPS.Open("c:\data\ConcordMA.txt")
IF rc = 1 THEN
rc = MyGPS.GetFix(myFix)
// process fix data ELSE
// process error message with user function
errmsg = uf_display_error("Fix Error", rc)
END IF
Opens a communications channel for a SerialGPS object and initializes data handlers.
SerialGPS objects
GPSname.Open ( )
Argument |
Description |
|---|---|
GPSname |
Name of the SerialGPS object. |
Integer. Returns 1 for success and a negative number for any error. The following is a list of possible error codes and their meanings:
-10 Invalid object. Could occur if the SerialGPS object instance is corrupted.
-18 Already Open. An Open request was issued and the object is already open.
Use this function to open a communications channel for a SerialGPS object and initialize it so that it can be used to obtain GPS information. For the SerialGPS object, you must previously set the SerialPort property and optionally set the ConfigParams proeperty prior to calling this function.
The following lines create a SerialGPS object, retrieve information about the current position fix, and test the validity of the GPSFix object:
SerialGps myGPS GPSFix myFix
Integer rc MyGPS = CREATE SerialGPS rc = myGPS.Open() IF rc = 1 THEN rc = MyGPS.GetFix(myFix)
IF rc = 1 THEN IF myFix.IsFixValid THEN // process fix data END IF ELSE
// process error message
END IF
END IF
Opens a communications channel for a Camera object and initializes data handlers.
Camera objects
cameraname.Open ( AppWindow )
Argument |
Description |
|---|---|
cameraname |
Name of the Camera object. |
AppWindow |
GraphicObject that is required by some camera drivers. Typically you use the name of the main application window. |
Integer. Returns 1 for success, and one of the following negative values if an error occurs:
Use this function to open a communications channel for a Camera object and initialize it so that it can be used to capture images.
You must set the camera type before you call Open. You must also set either the port or the folder property of the Camera object, depending on the type of camera device you are using. You can set these properties in the Properties view for a Camera object or in a script. The following table describes the properties you need to set for different devices:
Device |
CameraType specifier |
Port or Folder property (value) |
|---|---|---|
Windows Mobile 5 |
1 |
— |
VEO 130S |
11 |
Port (set to "SIO1:") |
HP Photosmart |
71 |
Port (set to "SIO1:") |
HTC using the IA Camera Wizard |
81 |
Folder (set to the path on the Windows CE device) |
The following code creates a Camera object that interfaces with an HP Photosmart camera:
Camera myCamera myCamera = CREATE Camera
myCamera.Port= "SIO1:"
myCamera.CameraType=71 myCamera.Open(w_myphoto_main) ...
Opens an SMSSession object.
SMSSession objects
SMSSessionname.Open ( smsproto, msgmodes )
Argument |
Description |
|---|---|
SMSSessionname |
Name of the SMSSession object. |
smsproto |
An SMSProtocol structure. |
msgmodes |
A long value indicating whether the SMSSession object is opened in send or receive mode. Values can be:
|
Integer. Returns 1 for success and a negative number for any error.
You can send SMS messages from applications running on any supported Windows CE platform, but you can receive SMS messages only in applications running on Windows Mobile platforms. To receive messages, you also need to deploy a shim DLL that installs with PocketBuilder, and you must register the DLL with the operating system where you deploy it.
For more information about receiving SMS messages in a PocketBuilder application, see the chapter on working with native objects and controls in the Users Guide.
Use one of these syntaxes to open a file and select its access mode. Use instead of FileOpen to interface directly with the underlying file system when you want to read from or write to a device connected through BlueTooth or other connection tools. The Open function maps to the Windows CE CreateFile command.
FileDirect objects
Integer instancename.Open ( filename, accessmode, {sharemode, creationdisposition, attributes})
Integer. Returns 1 for success and a negative number for any error. Error codes are:
Use this function to open a file in read or write mode. The FileDirect object supports only the synchronous style of file input or output; further file-related commands cannot be processed until the indicated file is successfully opened or an error in opening the file is caught. The Open function calls the CreateFile method on the device operating system.
The following example calls the FileDirect user object nvo_fileDirect to open a file, read some data, store the data in a blob variable, and close the file:
Integer li_ret, li_AmountRead
Blob lb_data
li_ret = nvo_fileDirect.Open ("MyDoc.txt", stgRead!)
li_ret = nvo_fileDirect.Read (lb_data, 100, li_amountRead)
li_ret = nvo_fileDirect.Close ( )
Opens the specified trace file for reading.
TraceFile object
instancename.Open ( filename )
Argument |
Description |
|---|---|
instancename |
Instancename of the TraceFile object |
filename |
A string identifying the name of the trace file you want to read |
ErrorReturn. Returns one of the following values:
Success!—The function succeeded
FileAlreadyOpenError!—The specified trace file has already been opened
FileOpenError!—The trace file can not be opened for reading
FileInvalidFormatError!—The file does not have the correct format
EnterpriseOnlyFeature!—This function is supported only in the Enterprise edition of PowerBuilder
SourcePBLError!—The source libraries cannot be found
You use this syntax to access the contents of a specified trace file created from a running PocketBuilder application. You can then use the properties and functions provided by the TraceFile object to perform your own analysis of tracing data instead of using the available modeling objects.
This example opens a trace file:
TraceFile ltf_file
String ls_filename
ltf_file = CREATE TraceFile
ltf_file.Open(ls_filename)
...
