Passing Definitions to the DBMS Server

This chapter describes how definitions are passed to the DBMS Server.

IIudadt_register Routine

The DBMS Server accesses user-written code for new data types, functions, and operator capabilities by calling the routine IIudadt_register. This routine, which you must provide, is called at system startup. It fills in a pointer to a data structure that contains the definitions of any user-written data types, functions and function instances. The DBMS Server checks the definitions to ensure that they are correct and merges them with the existing data type manipulation objects.

This routine is called using the following syntax:

status=IIudadt_register(add_block);

Status has the data type II_STATUS. Add_block is a pointer to a field that must be set to point to a data structure of type IIADD_DEFINITION if you are adding new data types, functions, or function instances. If you are not adding new data types (or functions or function instances), set this pointer to zero. This is the default.

Note: If provided, IIADD_DEFINITION exists as a compiler-generated data area. Do not dynamically allocate this data area or place it on the stack.

Structure IIADD_DEFINITION Fields

The fields in the IIADD_DEFINITION data structure are as follows:

• add_risk_consistency

  This field, if set to IIADD_INCONSISTENT, tells the DBMS Server to start even if the values of the current add_major_id and add_minor_id fields do not agree with those in use by the Ingres recovery system. Setting this field is very dangerous and must only be done in test installations.

  If the add_risk_consistency field is set, the DBMS Server ignores any disagreements between the major and minor ID fields of the support processes and the system. This is very dangerous in a production environment.

• add_major_id and add_minor_id

  The DBMS Server uses these values to ensure that all support processes know about all the data types in the system, ensuring recoverability across the installation. When a support process starts up, it checks the major and minor ID values in this block against the major and minor ID values known to the system. If the major_id values are not equal and the process' minor_id is not equal to or greater than the system's, the process not does start.

  The add_major_id field represents the high order 4 bytes and the add_minor_id, the low order 4 bytes of an 8-byte value. The initial values of the major and minor IDs, representing Ingres in the original state, are 0x80000000 and 0, respectively.

  To display the current values for these fields, run the lockstat utility. Look for a lock with the key SYS_CONTROL II_DATATYPE_LEVEL. This key has an 8-byte value associated with it. The high order 4 bytes of this value represent the major_id and the low order 4 bytes, the minor_id. For example, the value associated with this key for the default data type level is '8000000000000000', representing the major_id of 0x80000000 and the minor_id of 0 which is Ingres in the original state.

  Increment the add_major_id field each time you add a new user-defined data type. User values for this field must be greater than 0. Minor_id must be greater than or equal to 0. Reset the add_minor_id field to 0 whenever the add_major_id is changed.

• add_l_user_string

  Specifies the length of the character string pointed to by add_user_string.

• add_user_string

  Pointer to a character string that is included in the system log.

• add_trace

  4-byte integer that can be filled with a bitmask to set trace functions to be provided during system startup. There are two bits used by trace functions:

  IIADD_T_LOG_MASK (1) directs the DBMS Server to place a number of trace messages in the various trace logs which exist in the system. While operating the DBMS Server, defining II_DBMS_LOG to a file causes the DBMS Server to place copies of the system error log messages in that file. If the IIADD_T_LOG_MASK bit is set, user-defined abstract data type initialization places status and error messages in this file.

  IIADD_T_FAIL_MASK (2) directs the system to shut down if there are failures while initializing the user-defined data types. This is useful in test situations.

  By default, the system ignores any errors encountered in processing new data type information and continues startup as if no user information was provided.

• add_count

  Must be set to the sum of the add_dt_cnt, add_fo_cnt, and add_fi_cnt fields.

• add_dt_cnt

  A 4-byte integer field that must be set to the count of data types to be added.

• add_dt_dfn

  This field must point to an array of IIADD_DT_DFN structures that define new data types. (For instructions on filling in the IIADD_DT_DFN structures, see the chapter "Defining Data Types.") If the add_dt_cnt field is zero, set add_dt_dfn to zero.

• add_fo_cnt

  This field is a 4-byte integer that must be set to the count of functions to be added.

• add_fo_dfn

  This field must point to an array of IIADD_FO_DFN structures that define new functions. For details, see the chapter "Defining Functions." If the add_fo_cnt field is zero, set add_fo_dfn to zero.

• add_fi_cnt

  This field is a 4-byte integer that must be set to the count of function instances to be added.

• add_fi_dfn

  This field must point to an array of IIADD_FI_DFN structures that define new function instances. For details, see the chapter "Defining Function Instances." If the add_fi_cnt field is zero, set add_fi_dfn to zero.

Server Routines Provided

A number of routines are provided for you to use through the callback block. When you use one of these functions, save the addresses of the routines used in your code before IIudadt_register() returns. After IIudadt_register() completes, the call_back_block address is no longer valid.

These routines all return II_STATUS values that specify their completion status.

The ii_cb_trace Routine—Output Provided Trace Messages

The ii_cb_trace routine outputs trace messages provided to it. The parameters for this routine are as follows:

• dispose_mask

  Specifies how to dispose of the message:

  • II_TRACE_FE_MASK

    Indicates that the string must be sent to the front end

  • II_TRACE_ELOG_MASK

    Indicates that the string must be sent to the error log

  • II_TRACE_TLOG_MASK

    Indicates that the string must go to the trace log only (II_DBMS_LOG)

• length

  Specifies the length of the string

• string

  Pointer to the string to be traced

Note: If II_DBMS_LOG is defined, messages going to the error log also appear in the trace log.

The ii_error_fcn Routine—Place Error Information in Status Control Block

This routine places error information in the status control block (scb). As a result, you do not need to know the internal scb format. The parameters for this routine are as follows:

• scb

  A pointer to the scb into which the error must be placed.

• err_num

  The error number to include in the message that goes to the scb.

• text

  A pointer to the character string to include in the message that goes to the scb.

The ii_lo_handler_fcn Routine—Move Through Large Object Segments

You can use this routine to move through large object segments. It is called with two arguments: an operation code, and a pointer to a pop_cb (peripheral operations control block). For details, see Large Objects and the Methods for Defining Function Instances for Large Objects.

The ii_init_filter_fcn Routine—Set Up Filter Function

This routine sets up the filter function for large objects. It is called with three arguments: a pointer to an scb, a pointer to an II_DATA_VALUE that describes the large object being input, and a pointer to an II_DATA_VALUE that describes the workspace provided. For details, see Large Objects and Methods for Defining Function Instances for Large Objects.

The ii_filter_fcn Routine—Perform Operation by Calling a User Routine

This routine performs an operation by calling back a user routine for each segment in the input object. It is called with the following arguments:

• A pointer to an scb
• Pointers to the II_DATA_VALUE's for the input and output segments
• Pointer to a function to be called
• A pointer to a workspace to be used (previously initialized by a call to the initialization function)
• A continuation indicator indicating whether this is the first time this has been used.

For details, see Large Objects and Methods for Defining Function Instances for Large Objects.