Script parameters

Named parameters have the following advantages over (deprecated) question marks:

Named parameters allow you to specify any subset of the available parameters in any order.
With the exception of in/out parameters, you can specify the same named parameter more than once within a script.
When you use named parameters, you can specify the remote ID in your scripts. This is the only way to specify the remote ID in scripts.
You can create your own named parameters. See User-defined named parameters.

You cannot mix named parameters and question marks in a single script.

There are four types of MobiLink named parameters. To specify a named parameter, you must prefix it with its type, as follows:

Type of named parameter	Prefix	Examples
System parameters.	s.	{ml s.remote_id}
Row parameters. (The column name. If the column contains spaces, enclose it in double quotes or square brackets.)	r.	{ml r.cust_id} {ml r."Column name"}
Old row parameters. (Only used in upload_update scripts to specify the pre-image column values. If the column name contains spaces, enclose it in double quotes or square brackets.)	o.	{ml o.cust_name} {ml o."Column name"}
Authentication parameters. See Authentication parameters.	a.	{ml a.1}
User-defined parameters. See User-defined named parameters.	u. or ui.	{ml u.varname} Use if the parameter if the parameter will be updated. User-defined parameters prefixed with u. are in/out. {ml ui.varname} Use if the parameter will only be referenced. User-defined parameters prefixed with ui. are input-only.

To reference a script parameter by name, enclose the parameter in curly braces and prefix it with ml, as in {ml parameter }. For example, {ml s.action_code}. The curly brace notation is an ODBC convention.

For convenience, you can enclose a larger section of code in the curly braces, as long as the section of code does not contain any schema names with the same name as a MobiLink script parameter. For example, each of the following upload_insert scripts are valid and equivalent:

INSERT INTO t ( id, c0 ) VALUES( {ml r.id}, {ml r.c0} )

and

INSERT INTO t ( is, c0 ) VALUES({ml r.id, r.c0})

and

{ml  INSERT INTO t ( id, c0 ) VALUES( r.id, r.c0 ) }

Note

To use named row parameters you may need to use the ml_add_column system procedure to store column information in the consolidated database, although most deployments using version 12 synchronization clients do not require this. See ml_add_column system procedure.

Note

Representing parameters with question marks has been deprecated in SQL scripts. It is strongly recommended that you use named parameters instead. See Named script parameters and User-defined named parameters.

Representing parameters with question marks is an ODBC convention. To use question marks in your MobiLink SQL scripts, place a single question mark in your script for each parameter. The MobiLink server replaces each question mark with the value of a parameter. It substitutes values in the order the parameters appear in the script definition.

The parameters must be in the order specified in Synchronization events. Some parameters are optional. A parameter is optional only if no subsequent parameters are specified. For example, you must use parameter 1 if you want to use parameter 2.

The following forms of comments are recognized:

Double hyphen prefix (--)
Double forward slash prefix (//)
Block commenting (/* */)

The first two forms cause the script text to be ignored until the end of a line. The third form causes all script text between the /* prefix and the */suffix to be ignored. Block commenting cannot be nested.

Any other type of vendor-specific comment is not recognized and should not be used to comment references to a named parameter.

System parameter	Event type	Event parameter is available in
action_code	connection	The action_code parameter is available in the following events: handle_error handle_odbc_error report_error report_odbc_error
authentication_status	connection	The authentication_status parameter is available in the following events: authenticate_parameters authenticate_user authenticate_user_hashed
bytes	connection and table	The bytes parameter is available in the following events: download_statistics upload_statistics
conflicted_deletes	connection and table	The conflicted_deletes parameter is available in the following events: upload_statistics
conflicted_inserts	connection and table	The conflicted_inserts parameter is available in the following events: upload_statistics
conflicted_updates	connection and table	The conflicted_updates parameter is available in the following events: upload_statistics
connection_retries	connection	The conflicted_retries parameter is available in the following events: synchronization_statistics
deadlocks	connection and table	The deadlocks parameter is available in the following events: synchronization_statistics (connection event) upload_statistics (connection and table events)
deleted_rows	connection and table	The deleted_rows parameter is available in the following events: download_statistics upload_statistics
error_code	connection	The error_code parameter is available in the following events: handle_error modify_error_message report_error
error_message	connection	The error_message parameter is available in the following events: handle_error handle_odbc_error modify_error_message report_error report_odbc_error
errors	connection and table	The errors parameter is available in the following events: download_statistics synchronization_statistics upload_statistics
event_name	connection and table	The event_name parameter is available in the following events: time_statistics
fetched_rows	connection and table	The fetched_rows parameter is available in the following events: download_statistics
file_authentication_code	connection	The file_authentication_code parameter is available in the following events: authenticate_file_transfer authenticate_file_upload
filename	connection	The filename parameter is available in the following events: authenticate_file_transfer authenticate_file_upload
file_size	connection	The file_size parameter is available in the following events: authenticate_file_upload
filtered_rows	connection and table	The filtered_rows parameter is available in the following events: download_statistics
generation_number	connection	The filtered_rows parameter is available in the following events: begin_publication end_publication
hashed_new_password	connection	The hashed_new_password parameter is available in the following events: authenticate_user_hashed
hashed_password	connection	The hashed_password parameter is available in the following events: authenticate_user_hashed
ignored_deletes	connection and table	The ignored_deletes parameter is available in the following events: upload_statistics
ignored_inserts	connection and table	The ignored_inserts parameter is available in the following events: upload_statistics
ignored_updates	connection and table	The ignored_updates parameter is available in the following events: upload_statistics
inserted_rows	connection and table	The inserted_rows parameter is available in the following events: upload_statistics
last_download	connection	The last_download parameter is available in the following events: begin_download end_download modify_last_download_timestamp modify_next_last_download_timestamp nonblocking_download_ack prepare_for_download
last_publication_download	connection	The last_publication_download parameter is available in the following events: begin_publication end_publication publication_nonblocking_download_ack
last_publication_upload	connection	The last_publication_upload parameter is available in the following events: begin_publication end_publication
last_table_download	table	The last_table_download parameter is available in the following events: begin_download begin_download_deletes begin_download_rows download_cursor download_delete_cursor end_download end_download_deletes end_download_rows
maximum_time	connection and table	The maximum_time parameter is available in the following events: time_statistics
minimum_time	connection and table	The minimum_time parameter is available in the following events: time_statistics
new_password	connection	The new_password parameter is available in the following events: authenticate_user
next_last_download	connection	The next_last_download parameter is available in the following events: generate_next_last_download_timestamp modify_next_last_download_timestamp
number_of_calls	connection and table	The number_of_calls parameter is available in the following events: time_statistics
odbc_state	connection	The odbc_state parameter is available in the following events: handle_odbc_error report_odbc_error
password	connection	The password parameter is available in the following events: authenticate_user
publication_name	connection	The publication_name parameter is available in the following events: begin_publication end_publication publication_nonblocking_download_ack
remote_id	connection and table	The remote_id parameter is available in the following events: authenticate_parameters (connection event) authenticate_user (connection event) authenticate_user_hashed (connection event) begin_download (connection and table event) begin_download_deletes (table event) begin_download_rows (table event) begin_publication (connection event) begin_synchronization (connection and table event) begin_upload (connection and table event) begin_upload_deletes (table event) begin_upload_rows (table event) download_cursor (table event) download_delete_cursor (table event) download_statistics (connection and table event) end_download (connection and table event) end_download_deletes (table event) end_download_rows (table event) end_publication (connection event) end_synchronization (connection and table event) end_upload (connection and table event) end_upload_deletes (table event) end_upload_rows (table event) generate_next_last_download_timestamp (connection) handle_error (connection event) handle_odbc_error (connection event) modify_error_message (connection event) modify_last_download_timestamp (connection event) modify_next_last_download_timestamp (connection event) modify_user (connection event) nonblocking_download_ack (connection event) prepare_for_download (connection event) publication_nonblocking_download_ack (connection event) report_error (connection event) report_odbc_error (connection event) resolve_conflict (table event) synchronization_statistics (connection and table event) time_statistics (connection and table event) upload_delete (table event) upload_fetch (table event) upload_fetch_column_conflict (table event) upload_insert (table event) upload_new_row_insert (table event) upload_old_row_insert (table event) upload_statistics (connection and table event) upload_update (table event)
remote_key	connection	The remote_key parameter is available in the following events: authenticate_file_transfer authenticate_file_upload
subdir	connection	The subdir parameter is available in the following events: authenticate_file_transfer authenticate_file_upload
subscription_id	connection	The subscription_id parameter is available in the following events: begin_publication end_publication publication_nonblocking_download_ack
synchronization_ok	connection and table	The synchronization_ok parameter is available in the following events: end_synchronization
synchronized_tables	connection	The synchronized_tables parameter is available in the following events: synchronization_statistics
table	connection and table	The table parameter is available in the following events: begin_download (table event) begin_download_deletes (table event) begin_download_rows (table event) begin_synchronization (table event) begin_upload (table event) begin_upload_deletes (table event) begin_upload_rows (table event) download_statistics (table event) end_download (table event) end_download_deletes (table event) end_download_rows (table event) end_synchronization (table event) end_upload (table event) end_upload_deletes (table event) end_upload_rows (table event) handle_error (connection event) handle_odbc_error (connection event) report_error (connection event) report_odbc_error (connection event) resolve_conflict (table event) synchronization_statistics (table event) time_statistics (table event) upload_statistics (table event)
total_time	connection and table	The total_time parameter is available in the following events: time_statistics
updated_rows	connection and table	The updated_rows parameter is available in the following events: upload_statistics
username	connection and table	The username parameter is available in the following events: authenticate_file_transfer (connection event) authenticate_file_upload (connection event) authenticate_parameters (connection event) authenticate_user (connection event) authenticate_user_hashed (connection event) begin_download (connection and table event) begin_download_deletes (table event) begin_download_rows (table event) begin_publication (connection event) begin_synchronization (connection and table event) begin_upload (connection and table event) begin_upload_deletes (table event) begin_upload_rows (table event) download_cursor (table event) download_delete_cursor (table event) download_statistics (connection and table event) end_download (connection and table event) end_download_deletes (table event) end_download_rows (table event) end_publication (connection event) end_synchronization (connection and table event) end_upload (connection and table event) end_upload_deletes (table event) end_upload_rows (table event) generate_next_last_download_timestamp (connection event) handle_error (connection event) handle_odbc_error (connection error) modify_error_message (connection error) modify_last_download_timestamp (connection error) modify_next_last_download_timestamp (connection event) modify_user (connection event) nonblocking_download_ack (connection event) prepare_for_download (connection event) publication_nonblocking_download_ack (connection event) report_error (connection event) report_odbc_error (connection event) resolve_conflict (table event) synchronization_statistics (connection and table event) time_statistics (connection and table event) upload_delete (table event) upload_fetch (table event) upload_fetch_column_conflict (table event) upload_insert (table event) upload_new_row_insert (table event) upload_old_row_insert (table event) upload_statistics (connection and table event) upload_update (table event)
warnings	connection and table	The warnings parameter is available in the following events: download_statistics synchronization_statistics upload_statistics