ecommon-sh

name	ecommon-sh
description	Use when auditing or reusing the shared EDirect shell functions that other Entrez Direct wrapper scripts source internally.
disable-model-invocation	true
user-invocable	true

ecommon-sh

Shared shell library for Entrez Direct wrappers. This file defines functions and global variables for argument parsing, retry logic, logging, and ENTREZ_DIRECT envelope handling. It is not a normal end-user CLI.

Quick Start

• Command: source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
• Local file: /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
• Observed library version when sourced: 24.0

When To Use This Tool

• Inspect the common behavior inherited by EDirect wrappers such as ecollect.
• Reuse shared shell functions like ParseCommonArgs, FinishSetup, RunWithLogging, and WriteEDirect in your own wrappers.
• Understand how EDirect normalizes flags, retries failed EUtils requests, and serializes ENTREZ_DIRECT metadata.
• Debug why multiple EDirect shell scripts share the same option handling, logging, or error-reporting behavior.

Common Patterns

# 1) Source the library and inspect its version variable
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
printf '%s\n' "$version"

# 2) Minimal wrapper skeleton that reuses common flag parsing and setup
#!/usr/bin/env bash
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh

ParseCommonArgs "$@"
shift "$argsConsumed"
FinishSetup

RunWithLogging nquire -url "$base" einfo.fcgi -db pubmed

# 3) Emit an ENTREZ_DIRECT envelope after a wrapper finishes
source /home/vimalinx/miniforge3/envs/bio/bin/ecommon.sh
WriteEDirect "pubmed" "$web_env" "$qry_key" "$num" "$stp" ""

Recommended Workflow

1. Treat ecommon.sh as a library file and source it into a shell or wrapper script instead of executing it directly.
2. Call ParseCommonArgs "$@" first if you want the standard EDirect flags and remember to shift "$argsConsumed" before handling tool-specific options.
3. Run FinishSetup before network work so base URL, API key, email, and related globals are initialized consistently.
4. Reuse RunWithLogging / retry helpers and WriteEDirect rather than reimplementing that behavior piecemeal.

Guardrails

• Running bash ecommon.sh or bash ecommon.sh -version is silently unhelpful in this environment: both paths exit with no useful output.
• The 24.0 version string is visible only after sourcing the file or through sibling wrappers that expose it.
• This library relies on mutable global state (db, input, web_env, qry_key, verbose, tranquil, and others). Source it into a clean shell context or isolate your wrapper logic carefully.
• Many helper functions eventually invoke sibling EDirect tools such as xtract, transmute, and nquire; sourcing the file does not guarantee those commands are on PATH.
• Autogenerated docs that treat ecommon.sh as a standalone command are misleading. The meaningful interface here is its function set, not its direct process invocation.