uctrl

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

uctrl 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, uctrl->pack is the connector-level packing code of the constant data indicated by uiflst->data.
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 (uinfo->dbtyp == 1) which only support fixed-size records (uinfo->fixrec is nonzero), udatlen is always equal to uctrl->urecsiz.
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 (uctrl->uopen == 1), and in the open modes 0 and 1. 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. udrv is not guaranteed to hold the NULL pointer when the connector workspace is not available.
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 udrviniU		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 uctrl->uftot below.
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 uctrl->ulock is nonzero. Record-level databases need to maintain uctrl->ulock because a table close may commit all changes on a table closure, while the logical Uniface transaction may not yet be completed. Relational databases do not need to maintain uctrl->ulock, because locks are released only when a transaction is completed.
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: -1—the table has been checked for existence and does not exist yet. 0—the table is not open. >0—the table exists and is open. In the dummy control block (see the introduction of this section) uopen is zero.
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: 0—the connector is allowed to identify a record by primary key, physical record or both of these together. <>0—the connector uses primary keys to identify records. For complete information on the interpretation of this element, see Select and Fetch connector requests.
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: First call. Last call. Symbolic values (FIRST_CALL and LAST_CALL) are available in the include file unidbm.h provided by Uniface. 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.

Valid connector requests

Connector request	Meaning
A	Logoff
C	Commit
D	Delete
F	Fetch
G	Global Transaction
I	Info
L	Logon
M	Message
N	Name table
O	Open
Q	Sql
R	Rollback
S	Select
U	Update
W	Write
Z	Close
*	Wildcard delete/nullify