Connecting to a Database (Synchronously)
Connect to a database called sandbox using a vnode called loathing.
Because OpenAPI functions generally return before the requested operation is complete, this example illustrates the use of “busy wait” loops to prevent the application from proceeding too soon.
1# start by importing pyngres
2
3import pyngres as py
4
5# initialize the OpenAPI to use the latest version
6
7inp = py.IIAPI_INITPARM()
8inp.in_timeout = -1
9inp.in_version = py.IIAPI_VERSION
10status = inp.in_status
11if status != py.IIAPI_ST_SUCCESS:
12 print('could not initialize the OpenAPI')
13 quit()
14
15# note the envHandle for future use
16
17envHandle = inp.in_envHandle
18
19# allocate a control block for IIapi_wait(), which will be called
20# in a loop after asynchronous OpenAPI functions are invoked
21# (such as Iiapi_connect()). The loop terminates when the requested
22# asynchronous operation is completed
23
24wtp = py.IIAPI_WAITPARM()
25wtp.wt_timeout = 0
26
27# define the connection target
28
29dbname = 'loathing::sandbox'
30
31# construct the target name as a NUL-terminated array of bytes
32# (i.e. a C string) by encoding dbname (which is a Python str and
33# hence meaningless to the OpenAPI). The database name in this
34# example includes a *vnode* name target = dbname.encode()
35
36target = dbname.encode()
37
38# Allocate a control block for IIapi_connect(). Initialize it
39# with the database target name; the previously noted envHandle; the
40# py.IIAPI_CT_SQL constant to indicate this will be an SQL
41# session, and set the timeout to -1 so the OpenAPI will wait
42# indefinitely for the connection to be established (or refused)
43
44cop = py.IIAPI_CONNPARM()
45cop.co_target = target
46cop.co_connHandle = envHandle
47cop.co_type = py.IIAPI_CT_SQL
48cop.co_timeout = -1
49
50# invoke IIapi_connect() then loop until the gp_completed flag indicates
51# the database connection request has finished
52
53py.IIapi_connect(cop)
54while not cop.co_genParm.gp_completed:
55 py.IIapi_wait(wtp)
56
57# the request can be completed successfully or it might fail for some
58# reason, such as an invalid database name
59
60# ************************************************************************
61# IMPORTANT: the status is returned only when the operation is complete;
62# do not test it before completion
63# ************************************************************************
64
65status = cop.co_status
66if status != py.IIAPI_ST_SUCCESS:
67 print('could not connect to the database')
68 quit()
69
70# when the connection is successfully established the returned
71# connection handle must be noted for future use in other OpenAPI
72# function invokations. The OpenAPI uses connection handles to allows it
73# to interact correctly with multiple simultaneous database
74# connections in the same application
75
76connHandle = cop.co_connHandle
77
78# once the connection is established the application can start sending
79# SQL statements to be executed, fetching query results, and controlling
80# the session behaviour (e.g. committing transactions, setting lockmodes,
81# changing display formats.)
82
83...
Once the connection is established the application can start sending SQL statements to be executed, fetching query results, and controlling the session behaviour (e.g. committing transactions, setting lockmodes, changing display formats.) All of these operations will need to be protected with busy-wait loops too.