uctrl
Exchanges general information between Uniface and the connector, and describes a table.
Description
Uniface initializes the uctrl
structure, known as a control block, before every call to the connector. Pointers in
the uctrl
structure give the connector access to various other Uniface data
structures and buffer spaces.
Dummy Control Block
Uniface manages a double-linked list of
uctrl
structures in Uniface virtual memory. The list starts with a dummy control
block that Uniface supplies to the connector in some connector requests.
- Logon
- Logoff
- Sql
- Commit
- Rollback
- Info
- Global transaction
The Message request may be supplied with the
first dummy uctrl
structure.
With the exception of this dummy control block,
every uctrl
structure corresponds to a specific table in a database. Only one uctrl
structure is guaranteed to be in real memory at any point in time.
The dummy uctrl
structure does
not describe a table and does not have an associated connector workspace. The connector can access
only the elements that are explicitly documented in the following connector request descriptions:
Before the connector is called, Uniface loads the
applicable uctrl
structure in real memory. (This uctrl
structure
is called the current control block in the description of the connector requests.) The connector
rarely needs to access uctrl
structures, other than the one Uniface initially
supplies.
In the other connector requests, Uniface supplies
the connector with a normal uctrl
structure which describes a table and has an
associated connector workspace when a workspace is requested in the Info connector call.
The current uctrl
structure is
passed to the connector as the parameter of the top-level connector function as described in
Integrate a User-Defined Database Connector
with Uniface.
Unless stated otherwise, every member is set by Uniface before the connector is called.
Members
Members | Description | |
---|---|---|
unsigned char func
|
The specified connector request to be performed. See Valid connector requests . | |
unsigned char *iobuf
|
Pointer to the general I/O buffer. | |
unsigned short pack
|
If equal to 7, this entry of the if
list describes a field or a physical record address. See also the description of the field
uiflst->data . If not equal to 7,
|
|
unsigned short
*sqlbuf
|
Pointer to the SQL buffer. | |
unsigned short
TMEnabled
|
If 1, the logon path is controlled by a transaction manager and therefore included in a global transaction. For more information, see Transactions. | |
unsigned short
two_phase
|
If 0, the two-phase commit protocol is not being used. The value three indicates that the two-phase commit protocol is being used. | |
short limhits
|
Used to specify the maximum number of hits
that can be returned by a query. This corresponds to the maxhits option
specified for the ProcScript read statement. |
|
short ucache
|
If 0, the select cache is disabled. Otherwise it is enabled. For more information, see Database Connector Requests. | |
struct uctrl *uchfw
|
Uniface virtual address of the next control block in the double-linked list of control blocks. | |
struct uctrl *uchbw
|
Uniface virtual address of the previous control block in the double-linked list of control blocks. | |
short udatlen
|
Total length of the record data in the
general I/O buffer. The total length is defined as the position (fldlst->ufpos )
of the last field plus its actual length (fldlst->uflen ). Uniface assigns a
value to udatlen before the Write and Update connector requests. The connector
must set the value when a record has been fetched from the database in the Select or Fetch
connector request. When a record is not successfully fetched, the connector must set
udatlen to zero explicitly. With record-level connectors
( |
|
unsigned char *udrv
|
Pointer to the connector workspace that
has been allocated by Uniface if a workspace is requested in the Info connector request. For more
information, see
uinfo. There is no workspace associated with the dummy uctrl
block (see the introduction of this section). The connector workspace can only be
accessed when the table is open ( Uniface guarantees that the contents of the connector workspace are preserved between calls to the connector that apply to the same table. It is not guaranteed, however, that the connector workspace is located at the same memory address with every call.
|
|
long udrverr
|
Must be set by the connector when it returns a negative return value to Uniface. Set by Uniface before a Message connector request is called. The value is an explanatory error code which may be an error code defined by either the DBMS or the connector. For more information, see Database Connector Requests. | |
short udrvini U |
Unique identification of the current logon path. For more information, see Database Connector Requests and Service Functions | |
short udrvnum
|
Connector sequence number. See also the
field uinfo->drvnum . |
|
unsigned char ufixvar
|
If non-zero, the table contains one or more variable-length fields. | |
struct ufldlst
*uflist
|
Pointer to the first of an array of
ufldlst structures which describe the fields in the table. For more information,
see ufldlst. |
|
short ufnum
|
The number of ufldlst structures in the
array pointed to by uctrl->uflist . The number of fields in the table is
(uctrl->ufnum - 1 ), since the first entry in the field list describes the
entity. See also the description of
|
|
unsigned char
*ufstring
|
Base address of the null-terminated
strings containing the model-level entity name and the field names. By ‘model level’ the name of
the entity as defined in the application model is meant, and not as possibly redefined in an
assignment file at application run time. See also the description of the
ufldlst->ufname field in the ufldlst structure. |
|
short uftot
|
Total number of fields in the table,
including the fields that are mapped by Uniface into the variable part of the record. See also the
description of uctrl->ufnum . |
|
struct uiflst
*uiflist
|
Pointer to the first of an array of
uiflst structures which describe the set of records to which the connector request
applies. For more information, see
uiflst. |
|
short uifnum
|
Number of uiflst
structures in the array pointed to by uctrl->uiflist . |
|
struct uidxlst
*uilist
|
Pointer to the first of an array of
uidxlst structures which describe the indexes associated with the table. For more
information, see uidxlst. |
|
short uinum
|
Number of uidxlst
structures in the array pointed to by uctrl->uilist . |
|
struct uctrl *ulink
|
Uniface virtual memory address of the
uctrl structure corresponding to the outer entity in a form. For more information, see uinfo->link in uinfo. |
|
short ulock
|
This field may be maintained by the
connector, but this is optional. If the connector maintains it and holds no locks in the table, the
value of uctrl->ulock must be zero. If the connector maintains the short ulock
and does have a lock, the value is non-zero. Also, if the connector does not maintain the short
ulock , the value is non-zero. Uniface will not close a table
temporarily to release resources when Record-level databases need to maintain
Relational databases do not need to
maintain |
|
short umaxhits
|
Indicates the step size of the stepped hitlist. Zero means all remaining records must be selected in one step. | |
unsigned char *umisc
|
Used for miscellaneous purposes. For more information, see Database Connector Requests. | |
unsigned char umode
|
The requested mode of the connector
request to be performed.For more information, see
Database Connector Requests. In the Info request, the mode is available in uinfo->mode
instead of uctrl->umode . |
|
unsigned char *uname
|
Pointer to the null-terminated table name after redefinition in an assignment file. As a result of entity assignment in an assignment file, the table name can be a full file specification for the file system of the operating system. If the DBMS supports the concepts of file names, the connector must use the full file specification to identify the table. If the DBMS does not support file names (as is the case with an RDBMS, for example), the connector must parse the full file specification and ignore everything except the table name. | |
unsigned char unoupd
|
If non-zero, update is not allowed on the table. | |
struct uordlst
*uolist
|
Pointer to the first of an array of
uordlst structures which describe the requested ordering of records. For more
information, see uordlst. |
|
short uonum
|
The number of uordlst
structures in the array pointed to by uolist . The connector can set this field to
zero in the Select mode 0 connector request to indicate that the DBMS is capable of selecting the
records in the requested order. |
|
short uopen
|
Indicates the state of the table:
In the dummy control block (see the
introduction of this section) |
|
unsigned char
uoverflw
|
If non-zero, the table is an overflow table. | |
short uprimlen
|
Length of the concatenated (‘compound’) primary key. | |
unsigned char
uprofil[2]
|
If either of the two values is non-zero, it
is the redefined value for the corresponding wildcard value as provided in
uinfo->uprofil[2] that is used. |
|
unsigned char uralen
|
Length of the PRA. Zero means PRAs are not supported. | |
unsigned char
urdbykey
|
Connector is requested to select:
For complete information on the
interpretation of this element, see |
|
short urecsiz
|
Maximum record length for this table in
this DBMS. If the DBMS supports variable-length records (see uinfo->fixrec in
uinfo), uctrl->urecsiz is either the Uniface maximum
record size (eight kilobytes) or the maximum record size of the DBMS (see
uinfo->recsiz in data structure
uinfo ), whichever is the shortest, even if the records in this table do not
have a variable part. |
|
unsigned char
usubmode
|
Indicates the start and end of one logical
sequence of Open mode 4, 5 and 6 requests.The value of usubmode is a bitwise
inclusive OR of the values:
Symbolic values
( Both bits are set when there is only one table, which has relationships only to itself. |
|
unsigned char
uversion
|
If non-zero, uversion is
the field number of the U_VERSION field which is present in the table. |
|
struct uwhrlst
*uwlist
|
Pointer to a uwhrlst
structure. For more information, see uwhrlst. |
|
short vsfnr
|
Indicator for segmented field handling. When this field has the value 0, no segmented fields need to be handled. |