uinfo

Supplies Uniface with basic information about the DBMS and the connector.

Description

The uinfo structure must be used by the connector to supply Uniface with basic information about the DBMS and the connector. The connector fills the uinfo structure in the Info call. The uinfo structure cannot be used for any other purpose.

Uniface defines and initializes the structure. The initial value of every element of the structure is zero (unless stated otherwise), which is by definition an appropriate default for all non-mandatory elements.

If incorrect or inconsistent information is stored in the uinfo structure, very obscure errors can occur in further processing.

To access the uinfo structure, the connector must define and initialize a pointer to it. In the Info mode 0 connector request, the address of the uinfo structure can be obtained as follows:

struct uinfo *info;
info = (struct uinfo *)ControlBlock->umisc;

where ControlBlock is the name of the parameter with the top-level connector function. For more information, see Integrate a User-Defined Database Connector with Uniface.

Members

uinfo Members
Member	Description
`long (SPEntry) (int Major, int Minor, void * funcs)`	Name of the ICC normal connector entry point used for service stored procedures.
`unsigned char aldate`	If non-zero, Uniface aligns values of model type Date (irrespective of the packing code or storage format) on a multiple of this value, counted from the start of the record.
`unsigned char aldoub`	If non-zero, Uniface aligns values of connector-level packing code F8 (double-precision eight-byte float) on a multiple of this value, counted from the start of the record.
`unsigned char ale9`	If non-zero, Uniface aligns values of connector-level packing code E9 on a multiple of this value, counted from the start of the record.
`unsigned char alfloat`	If non-zero, Uniface aligns values of connector-level packing code F4 (single-precision four-byte float) on a multiple of this value, counted from the start of the record.
`unsigned char ali2`	If non-zero, Uniface aligns values of connector-level packing code I2 (two-byte integers) on a multiple of this value, counted from the start of the record.
`unsigned char ali4`	If non-zero, Uniface aligns values of connector-level packing code I4 (four-byte integers) on a multiple of this value, counted from the start of the record.
`unsigned char alm6`	If non-zero, Uniface aligns values of connector-level packing code M6 on a multiple of this value, counted from the start of the record.
`unsigned char alrec`	If non-zero, Uniface pads each record up to a multiple of this value, counted from the start of the record.
`unsigned char alseg`	If non-zero, Uniface aligns a segmented field on a multiple of this value, counted from the start of the record.
`unsigned char altime`	If non-zero, Uniface aligns values of model type Time (irrespective of the packing code or storage format) on a multiple of this value, counted from the start of the record.
`unsigned char autovarsiz`	If non-zero, Uniface sets the variable-length attributes flag (mask value 4) in `ufldlst->ufbits` for fields with connector-level packing code pC, pU or pR when the maximum field length is greater than this value. Some DBMSs perform better on fixed-length fields than on variable-length fields, up to a certain length. For these DBMSs, the connector can support both fixed and variable-length fields. Specify the maximum length to use fixed-length fields in `uinfo->autovarsiz`.
`unsigned char bound`	If non-zero, Uniface aligns values of any fixed-length field on a multiple of this value, counted from the start of the record.
`unsigned char boundv`	If non-zero, Uniface aligns values of any variable-length field on a multiple of this value, counted from the start of the record. If the DBMS does not impose special alignment requirements on variable-length fields, `uinfo->boundv` must have the same value as `uinfo->bound`.
`unsigned char dbms[3]`	If the first character is not zero, Uniface presents the table name in `uctrl->uname` with a period (.) and the three characters appended.
`long dbmsmaxrecsiz`	If nonzero, this is the maximum record size supported by the DBMS for entities that do not contain any fields with a variable length packing code, such as C, VW, VR*, and so on. If it is zero it defaults to the value of `recsiz`.
`unsigned char dbtyp`	This field describes the type of DBMS and connector: 0—DBMS and connector are field-level. 1—DBMS and connector are record-level. With field-level connectors, Uniface sets and reads the field length of every individual field in `ufldlst->uflen`. With record-level connectors, Uniface assumes that the actual length of every field in the fixed part of the record equals the maximum field length in `ufldlst->ufmax`. If the DBMS supports variable-size records, see the description of `uinfo->fixrec`; the last field in the record can be of variable size. Uniface sets and reads `uctrl->udatlen` which determines the actual size of the record.
`unsigned char drvnum`	Connector sequence number as assigned by Uniface. The user-defined connectors UD0 through UD9 have sequence numbers 10 through 19.
`short drvsiz`	Amount of workspace in bytes needed by the connector per open table. The total amount of workspace Uniface allocates for the connector is the sum of the following (in bytes): `uinfo->drvsiz` + ( `uinfo->fields * uctrl->ufnum`) + ( `uinfo->indexes` *NumberOfIndexes ). NumberOfIndexes is the number of indexes associated with the table. For more infromation, see uidxlst. If this expression evaluates to a number greater than zero, Uniface allocates one workspace area of this size per control block (`uctrl` structure). The workspace is made available to the connector by means of the pointer `uctrl->udrv`. See also the description of `uinfo->fields` and `uinfo->indexes`.
`short fields`	Amount of workspace in bytes needed by the connector per field in the table. See also the description of `uinfo->drvsiz`.
`unsigned char filll`	Number of bytes Uniface allocates as leading fill characters for all fixed-length fields.
`unsigned char fillt`	Number of bytes Uniface allocates as trailing fill characters for all fixed-length fields.
`unsigned char filltv`	Number of bytes Uniface allocates as trailing fill characters for all variable-length fields.
`unsigned char fillv`	Number of bytes Uniface allocates as leading fill characters for all variable-length fields.
`unsigned char fixrec`	If non-zero, the DBMS supports only fixed nonzero-length records.
`short indexes`	Amount of workspace in bytes needed by the connector per index associated with a table. See also the description of `uinfo->drvsiz`.
`unsigned char lenseg`	If zero, the DBMS does not support segmented fields. Otherwise, it is the length of the segment ‘pointer’ of the DBMS.
`unsigned char like`	Indicates whether `like` must be used in the `uiflist`. If this field equals zero, the `like` operator is not used and the connector must scan pC, pR or pU field data for possible wildcard characters. If this field is equal to one, the `like` operator will be used and the connector needs to scan only the field data of type pR, pU or pC and wildcard characters must be replaced. See also `uinfo->profil`.
`unsigned char limkey`	If non-zero, Uniface automatically converts the fields of primary and candidate keys to printable characters from the ASCII character set. Caution: It is not recommended to use this option.
`unsigned char link`	If nonzero, Uniface maintains the field `uctrl->ulink`. This can be used with hierarchical DBMSs to gain access to the current occurrence of the parent table, when the connector is called for a child table. For more information, see ugethit.
`unsigned char mapmode`	Field used by the connector to indicate the desired behavior of Uniface with respect to the packing code table: 0—Using the old packing code table, the connector will never receive a packing code in `ufldlst->ucsfmt` or `ufldlst->udbfmt` from Uniface with a value larger than 255. 1—Using the new packing code table, the connector receives values in `ufldlst->ucsfmt` or `ufldlst->udbfmt` larger than 255. When no remapping is defined for the packing code, the data is exchanged in the format of the data type. 2—Using the new packing code table, the connector receives values in `ufldlst->ucsfmt` or `ufldlst->udbfmt` larger than 255. When no remapping is defined for the packing code, the data is exchanged using the default packing code for the data type as specified in `uinfo->updef`. Note: In future releases, the new packing code table will be mandatory. This means that the value 0 will be illegal for `uinfo->mapmode`.
`short maxcur`	If the number of open cursors is greater than this number, Uniface does not call the connector, except for the Close connector request. Uniface first tries to close one or more tables temporarily to release resources. The connector can use `uinfo->maxcur` to prevent violation of the maximum number of open cursors allowed by the DBMS. For that purpose, it must set `uinfo->maxcur` to the maximum number of open cursors allowed by the DBMS, minus the maximum number of cursors that the connector can open in one connector request. Uniface maintains a global count for the DBMS, but it does not maintain a count per logon path.
`short maxfield`	If nonzero, this is the maximum allowed length of the DBMS variable-length type that is used to implement the variable part of the Uniface record. The variable part of the record can have packing code pC, pR or pU, with the ‘variable-length’ flag (mask value 4) in `ufldlst->ufbits set`. Uniface uses `uinfo->maxfield` only to calculate the maximum size of the variable part of the record.
`short maxhits`	If nonzero, this is the size of one step of the Uniface stepped hitlist the connector advises to use. Zero indicates that the DBMS cannot support a stepped hitlist. If there is no clearly optimal value, a value of ten is recommended.
`unsigned char mode`	Indicates what kind of logon information the DBMS requires. The value of `mode` must be the bitwise inclusive OR of the applicable values from: 1—Database name required. 2—User name required. 4—Password required. 8—Uniface must not issue a logon request for the SQL workbench. The `mode` field is not initialized to zero by Uniface. If the DBMS does not require logon information, set `mode` explicitly to zero in the Info connector request.
`unsigned char noconst`	Indicates how the DBMS handles referential integrity. The value of `noconst` must be the bitwise inclusive OR of the applicable values from: 1—The DBMS checks referential integrity on Delete. 2—The DBMS checks referential integrity on Update. 4—Uniface must not Commit partial transactions. (When loading bulk data, Uniface regularly Commits by default to avoid locking overflow tables. This can violate referential integrity, however, as a logical unit of work is divided into multiple transactions). Specifying option 1 or 2 implies that relationship information from the Uniface Repository must be used to create the constraints in the database. For most field-level DBMS connectors maintained by Uniface, this is implemented using the Open modes 4, 5 and 6. For more information, see Database Connector Requests. User-defined connectors can simply avoid this implication by setting `noconst` to zero, meaning that Uniface must check referential integrity. For some connectors maintained by Uniface, this is implemented via the Create Table facility. User-defined connectors can simply avoid this implication by setting `noconst` to zero, meaning that Uniface must check referential integrity.
`unsigned char opnfil`	Maximum number of operating system files the connector can have open simultaneously for one open table.
`unsigned char optlock`	If nonzero, Uniface uses optimistic instead of cautious locking as the default locking strategy for this DBMS.
`unsigned char osegm`	If zero, Uniface uses the default method for overflow tables. In the default method, overflow tables contain two fields SEGM and DATA. SEGM contains the concatenated primary key of the primary table and a four-byte segment identification. If nonzero, Uniface will use an alternative method for overflow tables. In this method, overflow tables contain the primary key fields of the primary table and the fields SEGM and DATA. In this case, only SEGM contains the four-byte segment identification. For field-level connectors, the alternative is recommended.
`unsigned char profil[2]`	If `profil[0]` is nonzero, Uniface uses this character instead of binary 1 in the where structure data to represent the wildcard ‘’ (any pattern of any number of characters). If `profil[1`] is nonzero, Uniface uses this character instead of binary 2 in the where structure data to represent the wildcard ‘?’ (any character). Note:* This service is of limited use when the connector uses the if list. After Uniface has performed the substitution, it is not possible to distinguish between the mapped wildcard character and an identical character which is present in the data.
`unsigned char ralen`	If nonzero, this is the length of the PRA of the DBMS. Zero indicates that the DBMS does not support PRAs. If `ralen` is set to a nonzero value, the connector must provide the PRA with the following connector requests: Select if a PRA is requested by means of `uctrl->urdbykey`. Fetch if a PRA is requested by means of `uctrl->urdbykey`. Write. Update if the PRA has changed as a result of the Update. The connector must either provide the PRA with every request mentioned above, or give no support at all to the PRA.
`short recsiz`	If nonzero, this is the maximum record size supported by the DBMS for entities that contain any fields with a variable length packing code, such as C, VW, VR, and so on. The maximum record size used by Uniface is 8192 bytes. For entities that do not* contain any fields with a variable length, see the description of `dbmsmaxrecsiz`.
`short sizmod`	If nonzero, Uniface rounds record sizes up to the nearest multiple of this value.
`unsigned char supzero`	If nonzero, Uniface uses leading spaces instead of zeros with connector-level packing codes pN1-pN32.
`unsigned char tabname`	The following indicates the way Uniface treats the names of the overflow tables: 0—Uniface treats the entity names as file names by expanding USYS to the appropriate path. Uniface positions the ‘O’ for overflow tables. Truncation of the file name (length depending on the operating system) is possible. 1—Entity names are treated as table names. USYS is not expanded. Uniface positions the ‘O’ for overflow tables. Uniface does not truncate the table names. 2—Uniface issues table name request calls (‘N’) to let the DBMS connector determine the position of the ‘O’. USYS is not expanded. Uniface does not truncate the table names.
`unsigned char TMCapable`	If one, the connector supports global transactions and can be transaction management controlled.
`unsigned char twophase`	If zero, the DBMS does not support the two-phase commit protocol. The value 3 indicates that the DBMS supports the two-phase commit protocol. In this case, the connector must be capable of handling Commit mode 1 and Commit mode 2 connector requests, for the first and second phases of the Commit, respectively. The effect of other values is currently undefined.
`unsigned char txtsearch`	If nonzero, Uniface allows retrieve profiles in fields in the variable part of the record. Uniface assumes in this case that the DBMS is capable of performing the requested selection (the service function `uhitchk` is not capable of performing selections on fields in the variable part of the record). Generally, `txtsearch` is only set with text retrieval systems, not with normal DBMSs.
`short updef[16]`	An array of default model-level packing codes that Uniface will use when no packing code is explicitly specified in the application model. Note that there is no default for Uniface data type ‘S’ (String), as Uniface itself sets this default to C40. See Default Model-Level Packing Codes . If any of the values is not specified, Uniface uses a DBMS-independent default.
`short upfmt[pMAXPACKING]`	An array with redefinitions of connector-level packing codes. Each entry defines how Uniface presents a specific connector-level packing code to the connector. Each entry in table 3-7 must be set to a connector-level packing code that is supported by the connector. Uniface does not check the validity of connector-level packing code redefinitions. `pMAXPACKING` is available in unidbm.h, supplied by Uniface. Currently, its value is 512. For more information on connector-level packing codes, see Connector-Level Packing Codes and Connector-Level Packing Codes.

Default Model-Level Packing Codes
Entry	Uniface data type
0	Reserved
1	Reserved
2	Reserved
3	N (Number)
4	F (Float)
5	D (Date)
6	T (Time)
7	E (Datetime)
8	B (Boolean)
9-15	Reserved

Connector-Level Packing Codes
Entry	Original connector-level packing code	Length	Possible redefinitions	Description	Uniface application model definitions: Data type Packing code
0	pC	n	pC, pU	Character string range 1-255	S	Cn
1	pU	n	pU	TRX range 32-126	S, R	Un
2	pR	n	pR, pU	Raw range 0-255	S, R	Sn
3	pLC	*	pC, pU	Remapped VC variable length	S	LC*
4	pLU	*	pU	Remapped VU variable length	S, R	LC*
5	pLR	*	pR, pU	Remapped VR variable length	S, R	LC*
6-7				Reserved
8-39	pN1-pN32	1-32	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	Numeric ASCII string	N, F	C1-C32
40-55	pP1-pP16	1-16	pN, pP, pQ, pI, pF,pG8, pM, pJ, pO	Packed decimal	N	P1-P16
56-71	pQ1-pQ16	1-16	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	Packed decimal	N	Q1-Q16
72-75	pI1-pI4	1-4	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	Binary integer	N, F	I1-I4
76	pI8	8	pN, pP, pG8, pM, pJ, pO, pQ, pI, pF	Binary integer	N, F	I8
77	pF4	4	pN, pF, pG8, pJ*	Float 4 bytes	N, F	F4
78	pF8	8	pN, pF, pG8, pJ*	Float 8 bytes	N, F	F8
79	pG8	8	pN, pF, pG8, pJ*	G_floating	N, F	G8
80-95	pD1-pD16	n	pD, pE	Dates	D	D1-D16
96-111	pT1-pT16	n	pT, pE	Times	T	T1-T16
112-127	pE1-pE16	n	pE*	Datetime	D, T, E	E1-E16
128-135	pB1-pB8	1	pB*	Booleans	B	B1-B8
136-143	pM1-pM8	n	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	Money, various	N	M1-M8
144-175	pJ1-pJ32	1-32	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	Numeric ASCII string, without decimal point	N, F	N1-N32
176-207	pO1-pO32	n	pN, pP, pQ, pI, pF, pG8, pM, pJ, pO	VAX trailing numeric string	N	O1-O32
208-239	pY1-pY32		pY, pR	User-defined numeric	N	Y1-Y32
240-247	pZ1-pZ8		pZ, pR	User-defined dates and times	D, T, E	Z1-Z8