Help >

ddlUdiStruct() - update structure for UDI field(s)

Version 7.11

ddlUdiStruct() - update structure for UDI field(s)

ddlUdiStruct() is used to maintain User Defined Indexes, or UDIs. It can perform the necessary index updates for record insertion, change, delete and undelete.

Prototype:

   void ddlUdiStruct(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList,              /* command argument list */
      WtInt32 ItemCount,
      WtInt32 *RecNoList,         /* [in] 1-rel TB RecNo */
      WtInt32 *OpcodeList,        /* [in] update type; Ref. UdiOpXxx */
      WtInt32 *StatusList,        /* [in/out] return item status */
      char *OldValueList,
      char *NewValueList);
 
      /* macros for ddlUdiStruct() param *Status ... */
      #define UdiGetStatusCode(s)  ((s) & 0xffff)
      #define UdiGetStatusParam(s) (((s) >> 16) & 0xffff)
       
      #define UdiPutStatus(s,v)      s = (v)
      #define UdiPutStatusCode(s,v)  s = (((s) & 0xffff0000) | ((v) & 0xffff))
      #define UdiPutStatusParam(s,v) s = (((s) & 0xffff) | ((((v) & 0xffff) << 16)))

      /* symbolic values for ddlUdiStruct() param *OpcodeList ... */
      #define UdiOpChange     4      /* change an existing record (already structured) */
      #define UdiOpCreate     5      /* create structure for an existing record */
      #define UdiOpDelete     6      /* delete structure for existing record */
      #define UdiOpUndelete   7
      /* Note: UdiOpChange consists of two steps:      */
      /* 1) Delete the old index value;                */
      /* 2) Insert the new index value;                */
      /* UdiOpChDel is the delete step of UdiOpChange; */
      /* UdiOpChIns is the insert step of UdiOpChange; */
      #define UdiOpChDel      8      /* change an existing record; delete op */
      #define UdiOpChIns      9      /* change an existing record; insert op */

Permitted values in OptnStr:

/E - continue processing if error occurs; reference Description of Parameter StatusList below; /F - blank fill ascii fields that contain the null character;

Form of ArgList:

<TableName> <RdName>

<TableName> represents the target Table name; <RdName> represents the name of the RD that describes each record in OldValueList and NewValueList. <RdName> can be the WildCard "*". In the case where <TableName> contains one or more Virtual Columns, the WildCard RD consists of all level 0 fields in the Virtual Schema; i.e., both literal fields and virtual fields.

Description:

ddlUdiStruct() is an index maintenance function for User Defined Indexes, or UDIs. Although UDI does not require a connection to literal data in the underlying database, it does require a connection to a literal record.

Description of Parameter ItemCount:

WtInt32 ItemCount is the number of items being submitted; each item is represented by the respective values in RecNoList, OpcodeList, StatusList, OldValueList, and NewValueList.

Description of Parameter RecNoList:

WtInt32 *RecNoList is an array containing ItemCount Thunderbolt 1-relative Record Numbers in table <TableName>;

Description of Parameter OpcodeList:

WtInt32 *OpcodeList is an array containing ItemCount Opcodes as defined above.

Description of Parameter StatusList:

WtInt32 *StatusList is an array containing ItemCount status words that are returned to the caller by ddlUdiStruct(). After an item has been processed successfully, zero is stored into *StatusList. If an item cannot be processed successfully, an error code is stored into *StatusList; in most cases, an additional error parameter is stored into the upper half of *StatusList. Two macros are defined in the #include file to access the components of *StatusList:       UdiGetStatusCode(*StatusList)       UdiGetStatusParam(*StatusList) For invalid values of *RecNoList and *OpcodeList, status is 211; there is no param. All other status codes result from the structure process; in these cases, the param is the 1-relative position in <RdName> of the offending index. If the /E option is not present, processing terminates after the first error. However, if the /E option is present, processing continues regardless of errors. [For every index, there is an internal pointer called end-of-structured-information, or EOSI. This is the record number of the highest indexed record. When creating a new index value with UdiOpCreate, the record number must be <= EOSI+1. When updating an existing index value with UdiOpChange etc, the record number must be <= EOSI.] If the record number/EOSI relation is not met, the requested index update is not performed. If the /E option is not present, this condition is not diagnosed. If the /E option is present, this condition results in error code 121.

Description of Parameter OldValueList:

char *OldValueList is a buffer containing ItemCount record images; each of whose contents and length are defined by the Record Description <RdName>; there is no delimiter between record images. See additional comments under *NewValueList.

Description of Parameter NewValueList:

char *NewValueList is a buffer containing ItemCount record images; each of whose contents and length are defined by the Record Description <RdName>; there is no delimiter between record images. Each value of *OpcodeList requires a different configuration of *OldValueList and *NewValueList. In cases where data is not required, there must still be fillers to act as place holders. The specific configurations are: Opcode OldValue NewValue UdiOpChange Yes Yes UdiOpChDel Yes No UdiOpChIns No Yes UdiOpCreate No Yes UdiOpDelete Yes No UdiOpUndelete No Yes

Values returned in Control Structure:

Control.Ans1	Incoming ItemCount
Control.Ans2	Number of items processed
Control.Status	Error code 211 is returned by ddlUdiStruct() if 1) a value in the *OpcodeList is < 0 or > 9 [UdiOpMax] 2) a value in *RecNoList is < 0 or > current last recno

Back to top