db2se register_gc command

The db2se register_gc command registers a geocoder.

This command registers a geocoder so that it can be used then to geocode values in a table and store or update the resulting geometry value. The information about registered geocoders is available from the DB2GSE.ST_GEOCODERS catalog view.

Authorization

The user ID must have DBADM and DATAACCESS authority on the spatially enabled database to run this command.

Command syntax

db2se register_gc command

Read syntax diagramSkip visual syntax diagramregister_gcdatabase_name-userIduser_id-pwpassword -geocoderNamegeocoder_name -functionSchemafunction_schema-functionNamefunction_name -defaultParameterValuesdefault_param_values-parameterDescriptionsparameter_descriptions-vendorvendor_name-descriptiondescription_string

Command parameters

Where:
database_name
Specifies the name of the database for which you want to register a geocoder.
-userId user_id
Specifies the database user ID that has DATAACCESS authority on the database indicated by database_name.
-pw password
Specifies the password for user_id.
-geocoderName geocoder_name
Uniquely identifies the geocoder that you want to register. The geocoder_name value is converted to uppercase unless you enclose it in double quotation marks. The maximum length for this parameter is 128 characters.
-functionSchema function_schema
Specifies the schema name for the function that implements this geocoder. If this parameter is not specified, the value in the CURRENT SCHEMA special register is used as the schema name for the function.

The function_schema value is converted to uppercase unless you enclose it in double quotation marks.

-functionName function_name
Specifies the unqualified name of the function that implements this geocoder. The function must already be created and listed in the SYSCAT.ROUTINES catalog view.

The function_name value, together with the implicitly or explicitly defined function_schema value, must uniquely identify the function.

The function_name value is converted to uppercase unless you enclose it in double quotation marks.

-defaultParameterValues default_parameter_values
Specifies the list of default geocoding parameter values for the geocoder function.
You must specify the parameter values in the order that the function defined them, and separate them with a comma. For example:
default_parm1_value,default_parm2_value,...
Each parameter value must be an SQL expression. Follow these guidelines to specify default parameter values:
  • If a value is a string, enclose it in single quotation marks.
  • If a parameter value is a number, do not enclose it in single quotation marks.
  • If the parameter value is null, cast it to the correct type. For example, specify the following expression to indicate a NULL for an integer parameter:
    CAST(NULL AS INTEGER)
  • If the geocoding parameter is to be a geocoding column, do not specify a default parameter value.

Use two consecutive commas (...,,...) to omit default values for parameters that you indicate when you set up geocoding or run geocoding in batch mode by using the -parameterValues parameter with the db2se setup_gc command or the db2se run_gc command.

The maximum length for this parameter is 32,672 characters.

-parameterDescriptions parameter_descriptions
Specifies the list of geocoding parameter descriptions for the geocoder function. The maximum length for this parameter is 32,672 characters.
Each parameter description that you specify explains the meaning and usage of the parameter, and can be up to 256 characters long. The descriptions for the parameters must be separated by commas and must appear in the order of the parameters as defined by the function. To use a comma within the description of a parameter, enclose the string in single or double quotation marks. For example: 
description,'description2, which contains a comma',description3
-vendor vendor_name
Specifies the name of the vendor who implemented the geocoder. The maximum length for this parameter is 128 characters.
-description description_string
Describes the geocoder by explaining its application. The maximum length for this parameter is 256 characters.

Usage notes

The return type for the geocoder function must match the data type of the geocoded column. The geocoding parameters can be either a column name (called a geocoding column) which contains data that the geocoder needs. For example, the geocoder parameters can identify addresses or a value of particular meaning to the geocoder, such as the minimum match score. If the geocoding parameter is a column name, the column must be in the same table or view as the geocoded column.

The return type for the geocoder function serves as the data type for the geocoded column. The return type can be any Db2® data type, user-defined type, or structured type. If a user-defined type or structured type is returned, the geocoder function is responsible for returning a valid value of the respective data type. If the geocoder function returns values of a spatial type, that is ST_Geometry or one of its subtypes, the geocoder function is responsible for constructing a valid geometry. The geometry must be represented using an existing spatial reference system. The geometry is valid if you invoke the ST_IsValid spatial function on the geometry and a value of 1 is returned. The returned data from the geocoder function is updated in or is inserted into the geocoded column, depending on which operation (INSERT or UPDATE) caused the generation of the geocoded value.

Examples

The following example registers a geocoder named mygeocoder, which is implemented by a function named myschema.myfunction.
db2se register_gc mydb -geocoderName \"mygeocoder"\
        -functionSchema \"myschema\" -functionName \"myfnction\"
        -defaultParameterValues "1, 'string',,cast(null as varchar(50))"
        -vendor myvendor -description "myvendor geocoder
        returning well-known text"