The `dbms_os` package provides access to the operating system of the device the product runs on: running a command, reading and writing files, and inspecting files and directories. The package is available solely on products which run for a single user in that user's own context, such as Invantive Query Tool and Invantive Data Hub. It is absent on web-based products such as Invantive Cloud and Invantive Data Access Point. The table functions run, list_files and list_directories are used in a select through table(...); every other function of the package is called from PSQL, so its outcome is assigned to a variable of the block before it is used in a statement. ## `copy_file`: Copy a file. Copy a file. Parameters: - `source_path` (string, required): File name and path to copy. - `target_path` (string, required): File name and path to copy the file to. - `overwrite` (boolean, optional): Whether to replace the target when it exists. Defaults to false. ## `create_directory`: Create a directory. Create a directory and every directory above it which does not exist yet. An existing directory is left as it is. Parameters: - `directory_path` (string, required): Directory to create, together with all directories above it. ## `delete_file`: Delete a file. Delete a file and report whether it was there to begin with. Parameters: - `file_path` (string, required): File name and path to delete. - `ignore_missing` (boolean, optional): Whether a file which does not exist is acceptable. Defaults to true. ## `directory_exists`: Whether a directory exists. Report whether a directory exists. Parameters: - `directory_path` (string, required): Directory to check. ## `file_exists`: Whether a file exists. Report whether a file exists. A directory of that name is not a file. Parameters: - `file_path` (string, required): File name and path to check. ## `file_hash`: Hash of the contents of a file. Return the hash of the contents of a file as lower-case hexadecimal text, for instance to establish whether a build artefact changed. Parameters: - `file_path` (string, required): File name and path to hash. - `algorithm` (string, optional): Name of the algorithm: 'SHA-256', 'SHA-1', 'SHA-512' or 'MD5'. Defaults to SHA-256. ## `file_modified_utc`: Moment a file was last changed. Report the date and time (UTC) a file was last changed. Empty when the file does not exist. Parameters: - `file_path` (string, required): File name and path to report the moment of last change of. ## `file_size`: Size of a file. Report the size of a file in bytes. Empty when the file does not exist. Parameters: - `file_path` (string, required): File name and path to report the size of. ## `get_env`: Value of an environment variable. Return the value of an environment variable of the process. Empty when the variable is not set. Parameters: - `name` (string, required): Name of the environment variable. ## `list_directories`: List the directories in a directory. List the directories in a directory, optionally descending into the directories below. Each row holds the columns DIRECTORY_PATH, DIRECTORY_NAME, CREATION_DATE_TIME_UTC and MODIFIED_DATE_TIME_UTC. Parameters: - `directory_path` (string, required): Directory to list the directories of. - `search_pattern` (string, optional): Pattern the directory name must match. Defaults to all directories. - `recursive` (boolean, optional): Whether to descend into the directories below. Defaults to false. ## `list_files`: List the files in a directory. List the files in a directory, optionally descending into the directories below. Each row holds the columns FILE_PATH, FILE_NAME, SIZE, CREATION_DATE_TIME_UTC, MODIFIED_DATE_TIME_UTC and IS_READ_ONLY. Parameters: - `directory_path` (string, required): Directory to list the files of. - `search_pattern` (string, optional): Pattern the file name must match, such as '*.log'. Defaults to all files. - `recursive` (boolean, optional): Whether to descend into the directories below. Defaults to false. ## `move_file`: Move a file. Move or rename a file. Parameters: - `source_path` (string, required): File name and path to move. - `target_path` (string, required): File name and path to move the file to. - `overwrite` (boolean, optional): Whether to replace the target when it exists. Defaults to false. ## `open_file`: Open a file in its associated program. Hand a file to the program associated with it, as double-clicking it would. Only meaningful on a device with a desktop. Parameters: - `file_path` (string, required): File name and path to open. ## `open_url`: Open a URL in the browser. Hand a URL to the default browser. Only meaningful on a device with a desktop. Parameters: - `url` (string, required): URL to open. ## `path_combine`: Join the parts of a path. Join up to four parts into one path, using the directory separator of the platform. Avoids hard-coding a backslash in a query. Parameters: - `path1` (string, required): First part of the path. - `path2` (string, optional): Second part of the path. - `path3` (string, optional): Third part of the path. - `path4` (string, optional): Fourth part of the path. ## `path_full`: Absolute form of a path. Return the absolute path of the path supplied, resolving a relative path against the working directory of the product. Parameters: - `path` (string, required): Path to resolve. ## `quote_argument`: Quote one argument of a command line. Return one argument encoded such that the program started reads it back as the single argument it was meant to be. Needed when the command line is assembled by hand in the parameter 'arguments' of run, for instance because the number of arguments varies; the parameters 'argument1' and its successors already quote themselves. Parameters: - `argument` (string, required): Argument to quote. ## `read_file`: Read a file as binary value. Read the whole contents of a file and return it as a BLOB. Parameters: - `file_path` (string, required): File name and path to read. ## `read_file_text`: Read a file as text value. Read the whole contents of a file and return it as text, decoded using the encoding specified. Parameters: - `file_path` (string, required): File name and path to read. - `encoding` (string, optional): Name of the character encoding of the file, such as 'UTF-8' or 'Windows-1252'. Defaults to UTF-8. ## `run`: Run an operating-system command. Run a program and return its outcome as a single row holding the columns EXIT_CODE, TIMED_OUT, STDOUT, STDERR, STDOUT_TRUNCATED, STDERR_TRUNCATED, DURATION_MS, CPU_MS and PROCESS_ID. The program is started directly rather than through a shell, so pipes, redirection and wildcards are not interpreted. An exit code other than zero is reported rather than raised, unless raise_on_error says otherwise. Parameters: - `executable` (string, required): File name and path of the program to run. No shell is involved, so pipes, redirection and wildcards are not interpreted. - `working_dir` (string, optional): Directory to run the program in. It must exist. Defaults to the working directory of the product. - `timeout_ms` (int32, optional): Maximum duration of the command (ms). The command and all programs it started are ended by force when it is exceeded. Defaults to unlimited. - `stdin_text` (string, optional): Text handed to the standard input of the program, after which the input is closed. Defaults to no input at all. - `raise_on_error` (boolean, optional): Whether to raise an error when the command times out or ends on a non-zero exit code. Defaults to false, which reports both through the columns returned. - `arguments` (string, optional): Arguments added to the command line as they stand, without quoting. Suitable for a command line assembled elsewhere. - `argument1` (string, optional): Argument number 1 of the program, handed over as exactly one argument and quoted where needed. - `argument2` (string, optional): Argument number 2 of the program, handed over as exactly one argument and quoted where needed. - `argument3` (string, optional): Argument number 3 of the program, handed over as exactly one argument and quoted where needed. - `argument4` (string, optional): Argument number 4 of the program, handed over as exactly one argument and quoted where needed. - `argument5` (string, optional): Argument number 5 of the program, handed over as exactly one argument and quoted where needed. - `argument6` (string, optional): Argument number 6 of the program, handed over as exactly one argument and quoted where needed. - `argument7` (string, optional): Argument number 7 of the program, handed over as exactly one argument and quoted where needed. - `argument8` (string, optional): Argument number 8 of the program, handed over as exactly one argument and quoted where needed. - `argument9` (string, optional): Argument number 9 of the program, handed over as exactly one argument and quoted where needed. - `argument10` (string, optional): Argument number 10 of the program, handed over as exactly one argument and quoted where needed. ## `which`: Locate a program. Return the full file name and path of a program as it would be found along the search path, or empty when it is not there. Saves scanning a series of candidate directories. Parameters: - `executable` (string, required): Name of the program to look for, with or without extension. ## `write_file`: Write a binary value to a file. Replace the contents of a file by the BLOB supplied. Parameters: - `file_path` (string, required): File name and path to write. An existing file is replaced. - `contents` (blob, required): Contents of the file. - `create_directory` (boolean, optional): Whether to create the directory of the file when it does not exist yet. Defaults to false. ## `write_file_text`: Write a text value to a file. Replace the contents of a file by the text supplied, or add the text to the end of the file. Parameters: - `file_path` (string, required): File name and path to write. An existing file is replaced unless the contents are appended. - `contents` (string, required): Contents of the file. - `encoding` (string, optional): Name of the character encoding to write in, such as 'UTF-8' or 'Windows-1252'. Defaults to UTF-8. - `write_bom` (boolean, optional): Whether to start the file with a byte-order mark. Defaults to false, since a mark shows up as stray characters in a batch file or a CSV file read by another program. - `create_directory` (boolean, optional): Whether to create the directory of the file when it does not exist yet. Defaults to false. - `append` (boolean, optional): Whether to add the contents to the end of an existing file instead of replacing it. Defaults to false.