Uopy

https://rocketsoftware.github.io/uopy-demo/docs/
Admin
Uopy is an API library providing Python bindings for interacting with Rocket Software's UniObjects...
Tokens:58,430
Snippets:337
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example uopy.ini Configuration File

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

An example configuration file used to override default uopy settings.

```ini
[connection]
    host = uv1211.rocketsoftware.com
    account = XDEMO
    port = 41438
    timeout = 100
    service = udcs
    ssl = True

    [ssl_auth]
    server_cert_file="c:\temp\desktop-ppdt4ds.crt"

    [pooling]
    pooling_on = True
    max_wait_time = 60
    idle_remove_threshold = 300
    idle_remove_interval = 300
    min_pool_size = 5
    max_pool_size = 15

    [logging]
    level = DEBUG
    backup_count = 10
    log_data_max_size = 256
```

--------------------------------

### tx_start()

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Starts a transaction on the server.

```APIDOC
## tx_start()

### Description
Start a transaction on the server.

### Returns
- **None**

### Raises
- **UOError**
```

--------------------------------

### Session.tx_start()

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Starts a transaction on the server.

```APIDOC
## Session.tx_start()

### Description
Initiates a new transaction on the connected server.

### Returns
- **None**

### Raises
- **UOError**
```

--------------------------------

### uopy.ini Configuration File Example

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

An example of an external configuration file used to override default uopy settings.

```ini
[connection]
host = uv1211.rocketsoftware.com
account = XDEMO
port = 41438
timeout = 100
service = udcs
ssl = True

[ssl_auth]
server_cert_file="c:\temp\desktop-ppdt4ds.crt"

[pooling]
pooling_on = True
max_wait_time = 60
idle_remove_threshold = 300
idle_remove_interval = 300
min_pool_size = 5
max_pool_size = 15

[logging]
level = DEBUG
backup_count = 10
log_data_max_size = 256
```

--------------------------------

### Execute Remote Commands with uopy

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Examples demonstrating how to connect to a server and execute commands using the uopy library.

```python
>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("LIST VOC")
>>>     cmd.run()
>>>     print(cmd.response)
```

```python
>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("RUN BP SAYHELLOTO")
>>>     if cmd.status == uopy.EXEC_REPLY:
>>>         cmd.reply("MV loyal user")
>>>     print(cmd.response)
```

--------------------------------

### Select List Usage Example

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Demonstrates executing a SELECT command and reading the resulting record IDs.

```python
>>> cmd = Command("SELECT VOC WITH F1 = 'V'")
>>> cmd.run()
>>> select_list = List() # default is select list 0
>>> ids = select_list.read_list()
>>> print(ids[:5])
['LOAD.LANG', 'BEGIN.WORK', 'CLEARSELECT', 'RELEASE.ITEMS', 'SET.WIDEZERO']
```

--------------------------------

### Connect to an MV Database

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Examples of establishing a connection using keyword arguments, specific connection parameters, or a configuration dictionary.

```python
>>> session = uopy.connect(user = 'test', password ='test')
```

```python
>>> session = uopy.connect(host ='localhost', user = 'test', password ='test', account = 'HS.SALES',
            service=uopy.UV_SERVICE, port=31438)
```

```python
>>> config = {
        'user': 'test',
        'password': 'test',
        'service': 'udcs',
        'account': 'demo',
        'encoding': 'GB18030',
        'ssl': True
    }
>>> session = uopy.connect(**config)
```

--------------------------------

### SequentialFile Usage Example

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Demonstrates using SequentialFile within a context manager to ensure proper file closure.

```python
>>> with SequentialFile("BP", "TEST_SEQ", True) as seq_file: seq_file.write_line("This is test line 1") seq_file.write_line("This is test line 2") seq_file.seek(0) # go to the beginning of the file seq_file.write_line("This is test line 0") # overwrite the first line seq_file.seek(0) seq_file.read_line() This is test line 0 seq_file.read_line() This is test line 2
```

--------------------------------

### Execute Commands with uopy

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Examples of running basic commands and handling interactive replies using the uopy connection context.

```python
>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("LIST VOC")
>>>     cmd.run()
>>>     print(cmd.response)

>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("RUN BP SAYHELLOTO")
>>>     if cmd.status == uopy.EXEC_REPLY:
>>>         cmd.reply("MV loyal user")
>>>     print(cmd.response)
```

--------------------------------

### Execute Commands and Manage Transactions

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Examples of running database commands and using context managers for transaction control.

```python
>>>     cmd = uopy.Command("LIST VOC")
    >>>     cmd.run()
    >>>     print(cmd.response)
```

```python
>>> with uopy.connect(user="test", password="test") as session:
    >>>     session.tx_start()
    >>>     print(session.tx_is_active())
    >>>     ...
    >>>     session.tx_commit()
```

--------------------------------

### Write Named Fields Example

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Demonstrates the usage of write_named_fields to update specific fields in a file.

```python
field_value_list = [['Karen McGlone', ['03/29/2010', '03/30/2010', '03/31/2010', '03/30/2010'],
'3.50'], ['Jamie Klink', ['05/05/2010', '05/07/2010', '05/05/2010', '05/07/2010', '05/05/2010'], '4.82'],
['Mo Evans', ['08/23/2010', '08/20/2010', '08/26/2010', '08/22/2010', '08/25/2010', '08/22/2010'],'19.04']]
write_rs = test_file.write_named_fields(id_list, field_list, field_value_list)
for l in write_rs:
    print(l)
```

--------------------------------

### Configure Buffer Size

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Property to set or get the output buffer size. If unset, all output is returned at once.

```python
 96    @property
 97    def buffer_size(self):
 98        """int: The size of the output buffer for the Command object.
 99
100        If left unset, all the output of the command execution will be brought back at once.
101        If set explicitly, only the output of the specified size will be returned.
102
103        """
104        return self._buffer_size
```

--------------------------------

### Get Dictionary TYPE

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the TYPE field of a dictionary record.

```python
251    def get_type(self, record_id):
252        """Return the TYPE field of the dictionary record.
253
254        Args:
255            record_id (str or DynArray): the record id of the dictionary file.
256
257        Returns:
258            DynArray: the value of the TYPE field.
259
260        Raises:
261            UOError
262
263        """
264        return self.read_field(record_id, _DICT_TYPE_INDEX)
```

--------------------------------

### Get SQLType field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the SQLType field value from a dictionary record.

```python
220    def get_sql_type(self, record_id):
221        """Return the SQLType field of the dictionary record.
222
223        Args:
224            record_id (str or DynArray): the record id of the dictionary file.
225
226        Returns:
227            DynArray: the value of the SQLType field.
228
229        Raises:
230            UOError
231
232        """
233        return self.read_field(record_id, _DICT_SQLTYPE_INDEX)
```

--------------------------------

### Get SM field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the SM field value from a dictionary record.

```python
189    def get_sm(self, record_id):
190        """Return the SM field of the dictionary record.
191
192        Args:
193            record_id (str or DynArray): the record id of the dictionary file.
194
195        Returns:
196            DynArray: the value of the SM field.
197
198        Raises:
199            UOError
200
201        """
202        return self.read_field(record_id, _DICT_SM_INDEX)
```

--------------------------------

### Get NAME field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the NAME field value from a dictionary record.

```python
158    def get_name(self, record_id):
159        """Return the NAME field of the dictionary record.
160
161        Args:
162            record_id (str or DynArray): the record id of the dictionary file.
163
164        Returns:
165            DynArray: the value of the NAME field.
166
167        Raises:
168            UOError
169
170        """
171        return self.read_field(record_id, _DICT_NAME_INDEX)
```

--------------------------------

### Get LOC field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the LOC field value from a dictionary record.

```python
127    def get_loc(self, record_id):
128        """Return the LOC field of the dictionary record.
129
130        Args:
131            record_id (str or DynArray): the record id of the dictionary file.
132
133        Returns:
134            DynArray: the value of the LOC field.
135
136        Raises:
137            UOError
138
139        """
140        return self.read_field(record_id, _DICT_LOC_INDEX)
```

--------------------------------

### Retrieve File Information with fileInfoEx

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Demonstrates how to initialize a file object and call fileInfoEx to populate metadata attributes.

```python
>>> f = uopy.File('TEST')
>>> f.fileInfoEx()
>>> print(f.vocName)
>>> print(f.pathName)
>>> print(f.groupSize)
```

--------------------------------

### Get timeout property

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the timeout value configured for sequential file operations.

```python
117    @property
118    def timeout(self):
119        """int: the timeout for sequential file operations."""
120        return self._seq_timeout
```

--------------------------------

### Get and Set FORMAT Field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Methods to retrieve or update the FORMAT field of a dictionary record.

```python
 96    def get_format(self, record_id):
 97        """Return the FORMAT field of the dictionary record.
 98
 99        Args:
100            record_id (str or DynArray): the record id of the dictionary file.
101
102        Returns:
103            DynArray: the value of the FORMAT field.
104
105        Raises:
106            UOError
107
108        """
109        return self.read_field(record_id, _DICT_FORMAT_INDEX)
```

```python
111    def set_format(self, record_id, format_code):
112        """Set the FORMAT field of the dictionary record.
113
114        Args:
115             record_id (str or DynArray): the record id of the dictionary file.
116             format_code (str or DynArray): the value of the FORMAT field.
117
118        Returns:
119             None
120
121        Raises:
122             UOError
123
124        """
125        self.write_field(record_id, _DICT_FORMAT_INDEX, format_code)
```

--------------------------------

### SequentialFile.__init__

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new SequentialFile object and opens the specified file.

```APIDOC
## SequentialFile(file_name, record_id, create_flag=False, session=None)

### Description
Initializes a SequentialFile object to manage an MV Sequential File.

### Parameters
- **file_name** (str) - Required - The directory file name.
- **record_id** (str) - Required - The sequential file name.
- **create_flag** (boolean) - Optional - When False (default), do not create the file if nonexistent; otherwise, create the file if nonexistent.
- **session** (Session) - Optional - The Session object that the SequentialFile object is bound to. If omitted, the last opened Session in the current thread will be used.

### Returns
- **None**

### Raises
- **UOError**
```

--------------------------------

### Get and Set CONV Field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Methods to retrieve or update the CONV field of a dictionary record.

```python
65    def get_conv(self, record_id):
66        """Return the CONV field of the dictionary record.
67
68        Args:
69            record_id (str or DynArray): the record id of the dictionary file.
70
71        Returns:
72            DynArray: the value of the CONV field.
73
74        Raises:
75            UOError
76
77        """
78        return self.read_field(record_id, _DICT_CONV_INDEX)
```

```python
80    def set_conv(self, record_id, conv_code):
81        """Set the CONV field of the dictionary record.
82
83        Args:
84             record_id (str or DynArray): the record id of the dictionary file.
85             conv_code (str or DynArray): the value of the CONV field.
86
87        Returns:
88             None
89
90        Raises:
91            UOError
92
93        """
94        self.write_field(record_id, _DICT_CONV_INDEX, conv_code)
```

--------------------------------

### Calling a Cataloged BASIC Subroutine

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Demonstrates initializing a Subroutine object, setting input arguments, and executing the call to retrieve updated values.

```python
>>> sub = Subroutine("SAYHELLOTO", 1)
>>> sub.args[0] = "David"
>>> print(sub.args)
['David']
>>> sub.call()
>>> print(sub.args)
['Hello, David']
```

--------------------------------

### open()

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Opens the server-side file. If the create_flag is set to True, the file will be created if it does not already exist.

```APIDOC
## open()

### Description
Opens the server-side file, creating it if the create_flag is True and the file doesn't exist.

### Raises
- **UOError** - Raised if the operation fails.
```

--------------------------------

### Get and Set ASSOC Field

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Methods to retrieve or update the ASSOC field of a dictionary record.

```python
34    def get_assoc(self, record_id):
35        """Return the ASSOC field of the dictionary record.
36
37        Args:
38            record_id (str or DynArray): the record id of the dictionary file.
39
40        Returns:
41            DynArray: the value of the ASSOC field.
42
43        Raises:
44            UOError.
45
46        """
47        return self.read_field(record_id, _DICT_ASSOC_INDEX)
```

```python
49    def set_assoc(self, record_id, assoc):
50        """Set the ASSOC field of the dictionary record.
51
52        Args:
53            record_id (str or DynArray): the record id of the dictionary file.
54            assoc (str or DynArray): the value of the ASSOC field.
55
56        Returns:
57            None
58
59        Raises:
60            UOError
61
62        """
63        self.write_field(record_id, _DICT_ASSOC_INDEX, assoc)
```

--------------------------------

### Dictionary Record Field Accessors

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Methods to get and set various fields for dictionary records.

```APIDOC
## get_loc(record_id)

### Description
Returns the LOC field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.

### Returns
- **DynArray** - The value of the LOC field.

### Raises
- **UOError**

## set_loc(record_id, loc)

### Description
Sets the LOC field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.
- **loc** (str or DynArray) - Required - The value of the LOC field.

### Returns
- **None**

### Raises
- **UOError**

## get_name(record_id)

### Description
Returns the NAME field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.

### Returns
- **DynArray** - The value of the NAME field.

### Raises
- **UOError**

## set_name(record_id, name)

### Description
Sets the NAME field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.
- **name** (str or DynArray) - Required - The value of the NAME field.

### Returns
- **None**

### Raises
- **UOError**

## get_sm(record_id)

### Description
Returns the SM field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.

### Returns
- **DynArray** - The value of the SM field.

### Raises
- **UOError**

## set_sm(record_id, sm)

### Description
Sets the SM field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.
- **sm** (str or DynArray) - Required - The value of the SM field.

### Returns
- **None**

### Raises
- **UOError**

## get_sql_type(record_id)

### Description
Returns the SQLType field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.

### Returns
- **DynArray** - The value of the SQLType field.

### Raises
- **UOError**

## set_sql_type(record_id, sql_type)

### Description
Sets the SQLType field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.
- **sql_type** (str or DynArray) - Required - The value of the SQLType field.

### Returns
- **None**

### Raises
- **UOError**

## get_type(record_id)

### Description
Returns the TYPE field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.

### Returns
- **DynArray** - The value of the TYPE field.

### Raises
- **UOError**

## set_type(record_id, field_type)

### Description
Sets the TYPE field of the dictionary record.

### Parameters
- **record_id** (str or DynArray) - Required - The record id of the dictionary file.
- **field_type** (str or DynArray) - Required - The value of the TYPE field.

### Returns
- **None**

### Raises
- **UOError**
```

--------------------------------

### Initialize SequentialFile

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Constructor for the SequentialFile class, setting up file handles and session binding.

```python
    def __init__(self, file_name, record_id, create_flag=False, session=None):
        """Initializes a SequentialFile object.

        Args:
            file_name (str): the directory file name.
            record_id (str): the sequential file name.
            create_flag (boolean, optional): when False (default), do not create the file if nonexistent;
                otherwise, create the file if nonexistent.
            session (Session, optional): the Session object that the SequentialFile object is bound to.
                If omitted, the last opened Session in the current thread will be used.

        Returns:
            None

        Raises:
            UOError

        """
        super().__init__(session)

        self._seq_file_name = str(file_name)
        self._seq_record_id = str(record_id)
        self._is_opened = False
        self._seq_timeout = 0
        self._seq_file_handle = 0
        self._status = 0
        self._block_size = _DEFAULT_BLOCK_SIZE
        self._is_read_all = True

        if create_flag:
            self._seq_create_flag = 1
        else:
            self._seq_create_flag = 0

        self.open()
```

--------------------------------

### uopy.connect

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Establishes a connection to the UO server.

```APIDOC
## uopy.connect(user, password)

### Description
Establishes a connection to the back-end UO server using the provided credentials.

### Parameters
- **user** (str) - Required - The username for authentication.
- **password** (str) - Required - The password for authentication.
```

--------------------------------

### Manage Idle State

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Properties and methods to track and set the session's idle start time.

```python
133    @property
134    def idle_start_time(self):
135        return self._idle_start_time
```

```python
137    def start_idle(self):
138        self._idle_start_time = time.time()
```

--------------------------------

### Execute a UniVerse command

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Establish a connection and run a command using the uopy.Command class.

```python
>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("LIST VOC")
>>>     cmd.run()
>>>     print(cmd.response[-20:])
'68 records listed.\r\n'
```

--------------------------------

### Execute Database Transactions

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Perform transactions by starting, checking status, and committing changes within a session.

```python
>>> with uopy.connect(user="test", password="test") as session:
>>>     session.tx_start()
>>>     print(session.tx_is_active())
...
>>>     session.tx_commit()
```

--------------------------------

### Accessing uopy Configuration and Running Commands

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Displays the current runtime configuration settings and demonstrates executing a TCL command after establishing a connection.

```python
>>> import uopy
>>> uopy.config.connection
{'host': 'uv1211.rocketsoftware.com', 'account': 'XDEMO', 'port': 41438, 'timeout': 100, 'service': 'udcs',
'encoding': 'cp1252', 'ssl': True}

>>> uopy.config.pooling
{'pooling_on': True, 'min_pool_size': 5, 'max_pool_size': 15, 'max_wait_time': 60, 'idle_remove_threshold': 300,
'idle_remove_interval': 300}

>>> uopy.config.logging
{'level': 'DEBUG', 'format': 'standard', 'dir': './logs', 'file_name': 'uopy.log', 'max_size': 524288,
'backup_count': 10, 'unirpc_debug': False, 'log_data_max_size': 256}

>>> uopy.config.ssl_auth
{'client_auth_required': False, 'server_cert_file': 'c:\temp\desktop-ppdt4ds.crt', 'client_cert_file': '',
'client_key_file': '', 'check_hostname': False}

>>> with uopy.connect(user='test', password='test'):
>>>     cmd = uopy.Command("LIST VOC")
>>>     cmd.run()
>>>     print(cmd.response[-20:])
'68 records listed.
```

--------------------------------

### Get block_size property

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the block size used for read_block operations. Defaults to 8192 if unset.

```python
 98    @property
 99    def block_size(self):
100        """int: The block size for read_block(). The default value is 8192.
101
102        If left unset, read_block() will read the whole file back.
103        If set explicitly, it will be the maximum size of the data read_block() returns.
104
105        """
106        return self._block_size
```

--------------------------------

### List.__init__(list_no: int = 0, session: Session = None)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new List object to interact with a server-side select list.

```APIDOC
## List.__init__

### Description
Initializes a new List object. The object is used to control, access, and manipulate server-side select lists.

### Parameters
- **list_no** (int) - Optional - Select list number (default is 0).
- **session** (Session) - Optional - The Session object that the List object is bound to. If omitted, the last opened Session in the current thread will be used.
```

--------------------------------

### run()

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Executes the command on the remote server.

```APIDOC
### Method: run()

#### Description
Executes the command text associated with the Command object on the remote server.

#### Returns
- **None**

#### Raises
- **UOError**
```

--------------------------------

### Get Server @var Value

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves a specific server-side @var value using the provided enum.

```python
415    def get_atvar(self, atvar):
416        """Get a @var value from the server.
417
418        Args:
419            atvar: uopy.AtVar enum.
420
421        Returns:
422            DynArray: the value of the @var
423
424        Raises:
425            UOError
426
427        Examples:
428            >>> import uopy
429            >>> for atvar in uopy.AtVar:
430                    print(atvar.name, atvar.value)
431
432            LOG_NAME 1
433            PATH 2
434            USER_NO 3
435            WHO 4
436            TRANSACTION 5
437            DATA_PENDING 6
438            USER_RETURN_CODE 7
439            SYSTEM_RETURN_CODE 8
440            NULL_STR 9
441            SCHEMA 10
442            TRANSACTION_LEVEL 11
443
444            >>>
445            >>> with uopy.connect(user='test_user', password='test_password') as session:
446                    log_name = session.get_atvar(uopy.AtVar.LOG_NAME)
447                    account_path = session.get_atvar(uopy.AtVar.PATH)
448                    print(log_name)
449                    print(account_path)
450
451            test_user
452            C:\\U2\\ud82\\XDEMO
453
454        """
455        _logger.debug("Enter", atvar)
456
457        self._check_callable()
458
459        with self._lock:
460            in_packet = UniRPCPacket()
461            out_packet = UniRPCPacket()
462            out_packet.write(0, FuncCodes.EIC_GETVALUE)
463            out_packet.write(1, atvar.value)
464
465            self._rpc_connection.call(in_packet, out_packet)
466
467            resp_code = in_packet.read(0)
468            if resp_code == 0:
469                _logger.debug("Exit")
470                return DynArray(in_packet.read(1), self)
471            else:
472                raise UOError(code=resp_code)
```

--------------------------------

### Connect to Session

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a connection to the UniRPC server and performs login.

```python
262    def connect(self):
263        with self._lock:
264            if self.is_active:
265                _logger.warning("Session._connect: already connected.")
266                return
267
268            self._rpc_connection = UniRPCConnection(self._config)
269            self._rpc_connection.connect()
270            self._login()
271
272            # TODO initialize the transaction object
273            # self._transaction = self.Transaction()
274
275            thread_data.session = self
276            if self.db_type == "UV":
277                self._set_uv_version()
```

--------------------------------

### Dictionary(name, session=None)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new Dictionary object for a specified MV file.

```APIDOC
## Dictionary(name, session=None)

### Description
Initializes a Dictionary object to access an MV dictionary file.

### Parameters
- **name** (str) - Required - The name of the MV file to be opened.
- **session** (Session) - Optional - The Session object the Dictionary is bound to. If omitted, the last opened session in the current thread is used.

### Raises
- UOError
```

--------------------------------

### Get Character Encoding

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieves the character encoding used for converting between Python strings and MV data.

```python
156    @property
157    def encoding(self):
158        """The name of the character encoding used for conversion between Python unicode strings and MV data.
159
160        By default it is set to the local system's preferred encoding when server NLS is off, and to UTF-8 when
161        server NLS is on. However it can be overridden by the application to what reflects the actual encoding of
162        the server data.
163
164        """
165        return self._config[ENCODING]
```

--------------------------------

### DynArray.__init__

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new DynArray object.

```APIDOC
## DynArray.__init__(obj=None, session=None)

### Description
Initializes a DynArray object. It can be bound to a specific session or use the last opened session in the current thread.

### Parameters
- **obj** (any) - Optional - Can be a Python list, a string, a byte object, or another DynArray.
- **session** (Session) - Optional - The Session object that the DynArray object is bound to.

### Raises
- **UOError**
```

--------------------------------

### Initialize Command Object

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Constructor for the Command class, which binds to a session and sets initial state.

```python
55    def __init__(self, command_text=None, session=None):
56        """Initialize a Command object
57
58        Args:
59            command_text (str, optional): the TCL/ECL command to be executed on the remote server.
60            session (Session, optional): the Session object that the Command object is bound to.
61                If omitted, the last opened Session in the current thread will be used.
62
63        Raises:
64            UOError
65
66        """
67        super().__init__(session)
68
69        self._buffer_size = _EXEC_DEFAULT_BUFFER_SIZE
70        self._status = EXEC_COMPLETE
71        self._response = ""
72        self._next_block = ""
73        self.command_text = "" if command_text is None else command_text
74        self.at_system_return_code = 0
75        self.at_selected = 0
76        self._is_fetch_all = True
77        self._session.bind_command(self)
```

--------------------------------

### Command(command_text=None, session=None)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new Command object to be executed on a remote server.

```APIDOC
### Constructor: Command(command_text=None, session=None)

#### Description
Initializes a Command object for executing TCL/ECL commands.

#### Parameters
- **command_text** (str, optional) - The TCL/ECL command to be executed.
- **session** (Session, optional) - The Session object to bind the command to. If omitted, the last opened session in the thread is used.

#### Raises
- **UOError**
```

--------------------------------

### Open sequential file

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Opens a server-side file, optionally creating it if the create_flag is set. Raises UOError on failure.

```python
143    def open(self):
144        """Open the server-side file, creating it if the create_flag is True and the file doesn't exist.
145
146        Args:
147
148        Returns:
149
150        Raises:
151            UOError
152
153        """
154        _logger.debug("Enter", self._seq_file_name, self._seq_record_id)
155
156        if self._is_opened:
157            return
158
159        with self._lock:
160            in_packet = UniRPCPacket()
161            out_packet = UniRPCPacket()
162
163            out_packet.write(0, FuncCodes.EIC_OPENSEQ)
164            out_packet.write(1, self._session.encode(self._seq_file_name))
165            out_packet.write(2, self._session.encode(self._seq_record_id))
166            out_packet.write(3, self._seq_create_flag)
167
168            resp_code = self._call_server(in_packet, out_packet)
169            if resp_code != 0:
170                raise UOError(code=resp_code, obj=self._seq_file_name)
171
172            self._is_opened = True
173            self._seq_file_handle = in_packet.read(2)
174
175        _logger.debug("Exit")
```

--------------------------------

### SequentialFile Initialization and Context Management

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes the SequentialFile object and provides context manager support for automatic file handling.

```python
        super().__init__(session)

        self._seq_file_name = str(file_name)
        self._seq_record_id = str(record_id)
        self._is_opened = False
        self._seq_timeout = 0
        self._seq_file_handle = 0
        self._status = 0
        self._block_size = _DEFAULT_BLOCK_SIZE
        self._is_read_all = True

        if create_flag:
            self._seq_create_flag = 1
        else:
            self._seq_create_flag = 0

        self.open()

    def __enter__(self):
        if not self._is_opened:
            self.open()
        return self

    def __exit__(self, exec_type, exec_value, traceback):
        self.close()
```

--------------------------------

### Database Version and Login Procedures

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Internal methods for retrieving UniVerse version information and performing the authentication handshake.

```python
def _set_uv_version(self):
        # XTOOLSUB is in every version of uv and ud shipped to clients as a global subroutine
        sub = Subroutine("*XTOOLSUB", 4)
        sub.args[0] = 35
        sub.args[1] = ["VOC", "@ID='RELLEVEL'"]
        sub.args[2] = ""
        sub.args[3] = ""
        sub.call()
        # inside list ex.: ['01RELLEVEL', 'X', '14.1.1', 'NEWACC', '', '14.1.1']
        result = sub.args[2].list
        if len(result) == 6:
            uv_version = result[5]
            uv_version = int(uv_version.replace(".", ""))
            self._uv_version = uv_version
        else:
            _logger.warning("Could not read UV version in set_uv_version")
            self._uv_version = 0

    def _login(self):
        in_packet = UniRPCPacket()
        out_packet = UniRPCPacket()

        out_packet.write(0, _COMMS_VERSION)
        out_packet.write(1, _CS_VERSION)
        out_packet.write(2, self.encode(self._config[USER]))
        out_packet.write(3, mangle(self.encode(self._config[PASSWORD]), _COMMS_VERSION))
        out_packet.write(4, self.encode(self._config[ACCOUNT]))
        out_packet.write(5, self.encode(self._license_token))
        out_packet.write(6, _RESERVED)

        ip_int, hostname = get_host_info()

        out_packet.write(7, ip_int)
        out_packet.write(8, self.encode(self._mac_address))
        out_packet.write(9, self.encode(hostname))
        out_packet.write(10, b"")

        if config.pooling[POOLING_ON]:
            if is_cp_supported(self._rpc_connection.server_id):
                out_packet.write(11, 1)
            else:
                raise UOError(
                    code=ErrorCodes.UOE_CP_NOTSUPPORTED,
                    message="Database Server upgrade is needed.",
                )

        self._config[PASSWORD] = ""
        self.rpc_call(in_packet, out_packet)

        resp_code = in_packet.read(0)
        if resp_code == 0:
            self._nls_init()
            self._get_host_info()
            self.is_active = True
            self._transaction = Transaction(session=self)
        else:
            if in_packet.argument_count > 1:
                last_error = self.decode(in_packet.read(1))
                raise UOError(message=last_error)
            else:
                raise UOError(code=resp_code)
```

--------------------------------

### Transaction Control Methods

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Methods for managing server-side transactions, including starting, committing, rolling back, and checking status.

```python
529    def tx_start(self):
530        """Start a transaction on the server.
531
532        Args:
533
534        Returns:
535            None
536
537        Raises:
538            UOError
539
540        """
541        self._transaction.begin()
```

```python
543    def tx_commit(self):
544        """Commit the current transaction on the server.
545
546        Args:
547
548        Returns:
549            None
550
551        Raises:
552            UOError
553
554        """
555        self._transaction.commit()
```

```python
557    def tx_rollback(self):
558        """Roll back the current transaction on the server.
559
560        Args:
561
562        Returns:
563            None
564
565        Raises:
566            UOError
567
568        """
569
570        self._transaction.rollback()
```

```python
572    def tx_level(self):
573        """Return the current transaction level on the server
574
575        Args:
576
577        Returns:
578            int: the current transaction level
579
580        Raises:
581             UOError
582
583        """
584        return int(str(self.get_atvar(AtVar.TRANSACTION_LEVEL)))
```

```python
586    def tx_is_active(self):
587        """Check if a transaction is active on the server.
588
589        Args:
590
591        Returns:
592            True/False: in transaction or not
593
594        Raises:
595            UOError
596
597        """
598        resp = self.get_atvar(AtVar.TRANSACTION)
599        if resp == "" or resp == "0":
600            return False
601        else:
602            return True
```

--------------------------------

### Seek within sequential file

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Moves the file pointer to a specific offset relative to the start, current position, or end of the file.

```python
207    def seek(self, offset, relative_pos=0):
208        """Move the file pointer within the Sequential File by an offset position specified in bytes.
209
210        Args:
211            offset (int): specifies the number of bytes before or after relative_pos.
212                    A negative value moves the pointer to a position before aRelPos.
213            relative_pos (int): specifies the relative position within a file from which to seek. Default value is 0.
214                    0 (default) start from the beginning of the file.
215                    1 start from the current position.
216                    2 start from the end of the file.
217
218        Returns:
219            None
220
221        Raises:
222            UOError
223
224        """
225        _logger.debug("Enter", offset, relative_pos)
226
227        if relative_pos not in {_SEQ_FILE_START, _SEQ_FILE_CURR, _SEQ_FILE_END}:
228            raise UOError(code=ErrorCodes.UOE_EINVAL)
229
230        with self._lock:
231            in_packet = UniRPCPacket()
232            out_packet = UniRPCPacket()
233
234            out_packet.write(0, FuncCodes.EIC_SEEK)
235            out_packet.write(1, self._seq_file_handle)
236            out_packet.write(2, offset)
237            out_packet.write(3, relative_pos)
238
239            resp_code = self._call_server(in_packet, out_packet)
240
241            if resp_code != 0:
242                raise UOError(code=resp_code)
243
244        _logger.debug("Exit")
```

--------------------------------

### uopy.connect(**kwargs)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Establishes a connection to an MV Database. Returns a Session object, either newly created or retrieved from a connection pool.

```APIDOC
## uopy.connect(**kwargs)

### Description
Opens a connection to an MV Database. Users should use this function to obtain a Session object rather than instantiating one directly.

### Parameters
- **kwargs** (dict) - Required - Connection configuration parameters including: host, port, user, password, account, service, timeout, encoding, ssl, min_pool_size, max_pool_size. Only user and password are required.

### Returns
- **Session** (object) - A session object representing the database connection.

### Raises
- **UOError**
- **ValueError**

### Example
```python
import uopy

# Basic connection
session = uopy.connect(user='test', password='test')

# Connection with configuration dictionary
config = {
    'user': 'test',
    'password': 'test',
    'service': 'udcs',
    'account': 'demo',
    'encoding': 'GB18030',
    'ssl': True
}
session = uopy.connect(**config)
```
```

--------------------------------

### Seek within a Sequential File

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Moves the file pointer to a specific offset relative to the start, current position, or end of the file.

```python
    def seek(self, offset, relative_pos=0):
        """Move the file pointer within the Sequential File by an offset position specified in bytes.

        Args:
            offset (int): specifies the number of bytes before or after relative_pos.
                    A negative value moves the pointer to a position before aRelPos.
            relative_pos (int): specifies the relative position within a file from which to seek. Default value is 0.
                    0 (default) start from the beginning of the file.
                    1 start from the current position.
                    2 start from the end of the file.

        Returns:
            None

        Raises:
            UOError

        """
        _logger.debug("Enter", offset, relative_pos)

        if relative_pos not in {_SEQ_FILE_START, _SEQ_FILE_CURR, _SEQ_FILE_END}:
            raise UOError(code=ErrorCodes.UOE_EINVAL)

        with self._lock:
            in_packet = UniRPCPacket()
            out_packet = UniRPCPacket()

            out_packet.write(0, FuncCodes.EIC_SEEK)
            out_packet.write(1, self._seq_file_handle)
            out_packet.write(2, offset)
            out_packet.write(3, relative_pos)

            resp_code = self._call_server(in_packet, out_packet)

            if resp_code != 0:
                raise UOError(code=resp_code)

        _logger.debug("Exit")
```

--------------------------------

### File(name, dict_flag=0, session=None)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a File object to access a MultiValue hashed file on the remote server.

```APIDOC
## File(name, dict_flag=0, session=None)

### Description
Initializes a File object representing a MV hashed file on the remote server. It is the main mechanism for applications to access MV data remotely.

### Parameters
- **name** (str) - Required - The name of the MV File to be opened.
- **dict_flag** (int) - Optional - When set to uopy.DICT_FILE, the File object points to the dictionary file.
- **session** (Session) - Optional - The Session object that the File object is bound to.

### Raises
- **UOError**
```

--------------------------------

### Default uopy Configuration Parameters

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Default settings for connection, pooling, logging, and ssl_auth categories used by uopy.

```python
connection: {'host': 'localhost', 'account': 'XDEMO', 'port': 31438, 'timeout': 300, 'service': 'defcs',
    'encoding': 'cp1252', 'ssl': False}

    pooling: {'pooling_on': False, 'min_pool_size': 1, 'max_pool_size': 10, 'max_wait_time': 30,
    'idle_remove_threshold': 300, 'idle_remove_interval': 300}

    logging: {'level': 'WARNING', 'format': 'standard', 'dir': './logs', 'file_name': 'uopy.log', 'max_size': 524288,
    'backup_count': 5, 'unirpc_debug': False, 'log_data_max_size': 1024}

    ssl_auth: {'client_auth_required': False, 'server_cert_file': '', 'client_cert_file': '', 'client_key_file': '',
    'check_hostname': False}
```

--------------------------------

### File Class Initialization

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

The constructor for the File object, which initializes the connection to the specified MV file.

```python
 85    def __init__(self, name, dict_flag=0, session=None):
 86        """Initializes a File object.
 87        Args:
 88            name (str): the name of the MV File to be opened.
 89            dict_flag (int, optional): when it is uopy.DICT_FILE, then the File object points to the dictionary file.
 90                Otherwise, the target is the data file.
 91            session (Session, optional): the Session object that the File object is bound to.
 92                If omitted, the last opened Session in the current thread will be used.
 93
 94        Raises:
 95            UOError
 96
 97        """
 98        super().__init__(session)
 99
100        if name is None or len(name) == 0:
101            raise UOError(ErrorCodes.UOE_INVALIDFILENAME)
102
103        self._command = None
104        self._dict_flag = 1 if dict_flag else 0
105        self._status = 0
106        self._handle = None
107        self._type = 0
108        self._name = name
109        self._is_opened = False
110
111        self.open()
```

--------------------------------

### Access uopy configuration settings

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Retrieve current configuration dictionaries for connection, pooling, logging, and SSL authentication.

```python
>>> import uopy
>>> uopy.config.connection
{'host': 'uv1211.rocketsoftware.com', 'account': 'XDEMO', 'port': 41438, 'timeout': 100, 'service': 'udcs',
'encoding': 'cp1252', 'ssl': True}
```

```python
>>> uopy.config.pooling
{'pooling_on': True, 'min_pool_size': 5, 'max_pool_size': 15, 'max_wait_time': 60, 'idle_remove_threshold': 300,
'idle_remove_interval': 300}
```

```python
>>> uopy.config.logging
{'level': 'DEBUG', 'format': 'standard', 'dir': './logs', 'file_name': 'uopy.log', 'max_size': 524288,
'backup_count': 10, 'unirpc_debug': False, 'log_data_max_size': 256}
```

```python
>>> uopy.config.ssl_auth
{'client_auth_required': False, 'server_cert_file': 'c:\\temp\\desktop-ppdt4ds.crt', 'client_cert_file': '',
'client_key_file': '', 'check_hostname': False}
```

--------------------------------

### Subroutine(name, num_args, session=None)

Source: https://rocketsoftware.github.io/uopy-demo/docs/uopy.html

Initializes a new Subroutine object to represent a cataloged BASIC subroutine.

```APIDOC
### Constructor: Subroutine(name, num_args, session=None)

#### Description
Initializes a Subroutine object bound to a specific cataloged BASIC subroutine.

#### Parameters
- **name** (str) - Required - The name of the cataloged BASIC subroutine.
- **num_args** (int) - Required - The number of arguments defined on the cataloged subroutine.
- **session** (Session) - Optional - The Session object to bind to. If omitted, the last opened Session in the current thread is used.

#### Raises
- **UOError** - Raised if initialization fails.
```
Tokens:
Raw