clc script run

Runs the script in the given location.

Runs the given script.

Two kinds of scripts are supported:

Shell scripts: CLC commands or SQL
Advanced scripts: a Python-like language

The scripts may be in the following location:

Filesystem path: The path may optionally have the file:// prefix.

Shell Script

The script can contain:

SQL statements
CLC commands prefixed with backslash.
Comments starting with -- (double dash)

The script should have either .clc or .sql extension. Files with one of these two extensions are interpreted equivalently.

Advanced Script (BETA)

Advanced scripts are written in a Python-like language called Starlark. See this document for the language reference: https://github.com/google/starlark-go/blob/master/doc/spec.md

CLC commands are mapped to functions using a few straightforward rules:

If the command is a top level command, it is mapped as is. E.g., home command is mapped to the home() function.
Positional arguments are mapped to positional arguments in the function signature.
Flags are mapped to keyword arguments in the function signature.

Examples:

clc map set -n mymap foo bar ⇒ map_set("foo", "bar", name="mymap")

The script should have the .star extension. Only the filesystem is supported as a source for advanced scripts.

The following values are available for advanced scripts:

Value Description

Value	Description
`NANOSECOND`	1 nanoscond.
`MICROSECOND`	1 microsecond in nanoseconds.
`MILLISECOND`	1 millisecond in nanoseconds.
`SECOND`	1 second in nanoseconds.
`MINUTE`	1 minute in nanoseconds.
`HOUR`	1 hour in nanoseconds.
`DAY`	1 day in nanoseconds.

NANOSECOND

1 nanoscond.

MICROSECOND

1 microsecond in nanoseconds.

MILLISECOND

1 millisecond in nanoseconds.

SECOND

1 second in nanoseconds.

MINUTE

1 minute in nanoseconds.

HOUR

1 hour in nanoseconds.

DAY

1 day in nanoseconds.

The following functions are available for advanced scripts:

Function Description

Function	Description
`ARGS_LIST = argv()`	Returns the arguments passed to the script as a list. 0th item in the list is the script name.
DATA_TYPE_NAME = `data_type(DATA_VALUE)	Returns the type name of the given data value.
VALUE = `decode_data(DATA_VALUE)	Attempts to convert the data value to the corresponding script value.
`ERROR = last_error()`	Returns the last error or `None`. This function should be used together with the `--ignore-errors` flag.
`log_debug(STRING)`	Adds a DEBUG message to the CLC log.
`log_error(STRING_OR_ERROR)`	Adds an ERROR message to the CLC log. You can pass a `string` message or an `error`.
`log_warn(STRING)`	Adds a WARN message to the CLC log.
`map_clear(name=MAP_NAME)`	Clears the given Map.
`map_destroy(name=MAP_NAME)`	Deletes the given Map.
`LIST_OF_KEY_VALUE_TUPLES = map_entry_set(name=MAP_NAME)`	Returns a list of tuples that has the key in index 0 and the value in index 1. Keys and values are `data_value`s.
`ENTRY_VIEW = map_entry_view(KEY, name=MAP_NAME)`	`ENTRY_VIEW` is a dictionary with the following fields: `Key`: `data_value` `Value` `data_value` `Cost`: `integer` `Hits`: `integer` `Creation Time`: `integer` (UNIX time in milliseconds) `Expiration Time`: `integer` (UNIX time in milliseconds) `Last Access Time`: `integer` (UNIX time in milliseconds) `Last Stored Time`: `integer` (UNIX time in milliseconds) `Last Update Time`: `integer` (UNIX time in milliseconds) `Version`: `integer` `TTL`: `integer` (milliseconds) `Max Idle`: `integer` (milliseconds)
`VALUE = map_get(KEY, name=MAP_NAME)`	Returns the `data_value` for the given key.
`KEYS_LIST = map_key_set(name=MAP_NAME)`	Returns a list of keys as `data_value`.
`map_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)`	Locks a key in the Map.
map_load_all(name=MAP_NAME, replace=BOOL) or map_load_all(KEY1, …, name=MAP_NAME, replace=BOOL)`	Loads the given keys or all keys in the MapStore if no key was specifed.
`VALUE = map_remove(KEY, name=MAP_NAME)`	Deletes the given key from the Map and returns the corresponding value.
`map_set(KEY, VALUE, name=MAP_NAME)`	Sets the given value for the given key.
`SIZE = map_size(name=MAP_NAME)`	Returns the size of the Map.
`BOOL = map_try_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)`	Attempts to lock the entry for the given key. Returns `True` if successful.
`map_unlock(KEY, name=MAP_NAME)`	Unlocks the entry for the given key.
`VALUES_LIST = map_values(name=MAP_NAME)`	Returns the values in the Map as a list.
`BOOL = cpmap_compare_and_set(KEY, EXPECTED_VALUE, NEW_VALUE, name=CPMAP_NAME)`	Sets the value for the given key if it has the expected value.
`cpmap_delete(KEY, name=CPMAP_NAME)`	Deletes the value of a given key in a CPMap.
`cpmap_destroy(name=CPMAP_NAME)`	Deletes the CPMap and all the data in it.
`cpmap_get(KEY, name=CPMAP_NAME)`	Gets a value from the given CPMap.
`OLD_VALUE = cpmap_put(KEY, VALUE, name=CPMAP_NAME)`	Puts the given value in the given CPMap and returns the old value.
`VALUE = cpmap_remove(KEY, name=CPMAP_NAME)`	Removes the value of a given key in a CPMap and returns the old value.
`cpmap_set(KEY, VALUE, name=CPMAP_NAME)`	Sets a value in the given CPMap.
`TIME = now()`	Returns the current time in nanoseconds.
`LIST_OF_SERVICE_OBJECT_PAIRS = object_list() or OBJECT = object_list(SERVICE)`	Returns the data structure objects in the
`sleep(TIME)`	Sleeps for the given nanoseconds. For example, to sleep for 10 seconds: `sleep(10*SECOND)`.

ARGS_LIST = argv()

Returns the arguments passed to the script as a list. 0th item in the list is the script name.

DATA_TYPE_NAME = `data_type(DATA_VALUE)

Returns the type name of the given data value.

VALUE = `decode_data(DATA_VALUE)

Attempts to convert the data value to the corresponding script value.

ERROR = last_error()

Returns the last error or None. This function should be used together with the --ignore-errors flag.

log_debug(STRING)

Adds a DEBUG message to the CLC log.

log_error(STRING_OR_ERROR)

Adds an ERROR message to the CLC log. You can pass a string message or an error.

log_warn(STRING)

Adds a WARN message to the CLC log.

map_clear(name=MAP_NAME)

Clears the given Map.

map_destroy(name=MAP_NAME)

Deletes the given Map.

LIST_OF_KEY_VALUE_TUPLES = map_entry_set(name=MAP_NAME)

Returns a list of tuples that has the key in index 0 and the value in index 1. Keys and values are `data_value`s.

ENTRY_VIEW = map_entry_view(KEY, name=MAP_NAME)

ENTRY_VIEW is a dictionary with the following fields:

Key: data_value
Value data_value
Cost: integer
Hits: integer
Creation Time: integer (UNIX time in milliseconds)
Expiration Time: integer (UNIX time in milliseconds)
Last Access Time: integer (UNIX time in milliseconds)
Last Stored Time: integer (UNIX time in milliseconds)
Last Update Time: integer (UNIX time in milliseconds)
Version: integer
TTL: integer (milliseconds)
Max Idle: integer (milliseconds)

VALUE = map_get(KEY, name=MAP_NAME)

Returns the data_value for the given key.

KEYS_LIST = map_key_set(name=MAP_NAME)

Returns a list of keys as data_value.

map_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)

Locks a key in the Map.

map_load_all(name=MAP_NAME, replace=BOOL) or map_load_all(KEY1, …, name=MAP_NAME, replace=BOOL)`

Loads the given keys or all keys in the MapStore if no key was specifed.

VALUE = map_remove(KEY, name=MAP_NAME)

Deletes the given key from the Map and returns the corresponding value.

map_set(KEY, VALUE, name=MAP_NAME)

Sets the given value for the given key.

SIZE = map_size(name=MAP_NAME)

Returns the size of the Map.

BOOL = map_try_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)

Attempts to lock the entry for the given key. Returns True if successful.

map_unlock(KEY, name=MAP_NAME)

Unlocks the entry for the given key.

VALUES_LIST = map_values(name=MAP_NAME)

Returns the values in the Map as a list.

BOOL = cpmap_compare_and_set(KEY, EXPECTED_VALUE, NEW_VALUE, name=CPMAP_NAME)

Sets the value for the given key if it has the expected value.

cpmap_delete(KEY, name=CPMAP_NAME)

Deletes the value of a given key in a CPMap.

cpmap_destroy(name=CPMAP_NAME)

Deletes the CPMap and all the data in it.

cpmap_get(KEY, name=CPMAP_NAME)

Gets a value from the given CPMap.

OLD_VALUE = cpmap_put(KEY, VALUE, name=CPMAP_NAME)

Puts the given value in the given CPMap and returns the old value.

VALUE = cpmap_remove(KEY, name=CPMAP_NAME)

Removes the value of a given key in a CPMap and returns the old value.

cpmap_set(KEY, VALUE, name=CPMAP_NAME)

Sets a value in the given CPMap.

TIME = now()

Returns the current time in nanoseconds.

LIST_OF_SERVICE_OBJECT_PAIRS = object_list() or OBJECT = object_list(SERVICE)

Returns the data structure objects in the

sleep(TIME)

Sleeps for the given nanoseconds. For example, to sleep for 10 seconds: sleep(10*SECOND).

Usage:

clc script run [path/location] [flags] -- [parameter, ...]

Parameters:

Parameter Required Description Default

Parameter	Required	Description	Default
`parameter`	Optional	Arguments to be passed to an advanced script. The arguments can be retrieved using the `argv()` function.
`--echo`	Optional	Print the executed command. Not used in advanced script.	`false`
`--ignore-errors`	Optional	Ignore errors during script execution	`false`
`--debug`	Optional	Enable the debug mode for advanced scripts.	`false`

parameter

Optional

Arguments to be passed to an advanced script. The arguments can be retrieved using the argv() function.

--echo

Optional

Print the executed command. Not used in advanced script.

false

--ignore-errors

Optional

Ignore errors during script execution

false

--debug

Optional

Enable the debug mode for advanced scripts.

false

Global parameters

Parameter Description Default

--config, -c

Path to the configuration file in YAML format.

The following locations are tried in order for the existence of config.yaml

Current working directory
The parent directory of the clc executable
$CLC_HOME/default directory

--format, -f

Set the output format

csv
delimited: By tab characters
json
table

Interactive mode: table
Non-interactive mode: delimited

--log.level

Set the log level, one of:

debug
info
warning
error

info

--log.path

Set the log path. Use stderr to log to the screen (stderr).

$CLC_HOME/logs/YYYY-MM-DD.log where YYYY-MM-DD is today’s date.

--quiet, -q

Prevent displaying unnecessary output.

false

--verbose

Enable output with more information.

false

--timeout

Timeout for operation to complete.

The duration is a string in the form of AMOUNTunit where AMOUNT is an integer, and unit is one of the following:

ms: milliseconds
s: seconds
m: minutes
h: hours

Underscore (_) character is ignored in the AMOUNT. unit is optional and defaults to s if not specified.

The following are a few of the valid DURATIONs:

5: 5 seconds
5s: 5 seconds
10000ms: 10000 milliseconds
10_000_000ms: 10000000 milliseconds

This is a client-side timeout, the operation you started maybe in progress on the server-side even if the given timeout is exceeded.