====== HatchIT - FidoNet TIC File Hatcher ======

HatchIT (''[[dir:exec]]/hatchit.js'') announces (//hatches//) a file that is already in one of your local file directories into a FidoNet-style File Distribution Network (FDN) area.

For each system linked to that area, HatchIT creates a ''.tic'' file in your outbound directory and appends the file (and its TIC) to that link's ''.flo'' file, so your mailer sends both on the next session. The receiving system's TIC processor (e.g. [[module:TickIT]]) then imports the file on the other end.

HatchIT is the //outbound// counterpart to [[module:TickIT]], which processes //incoming// TIC files.

===== Requirements =====

  * The file must **already exist** in one of your file directories. HatchIT does not import files; use [[module:addfiles]] or ''[[module:postfile]].js'' for that.
  * The FDN area must be defined in ''[[dir:ctrl]]/tickit.ini'' (see [[module:TickIT]] / [[module:TickITcfg]]). HatchIT reads the area list and the per-area ''Links'' from that file.
  * Your mailer must use FLO-style outbound (BinkD or [[module:BinkIT]]). HatchIT logs an error and does nothing for other mailer types.
  * TIC passwords are read from the ''TicFilePwd'' key of the corresponding ''[node]'' section of ''[[config:sbbsecho.ini]]'' (managed via [[util:EchoCfg]] or AreaFix).

**Note:** if the area has no ''Links'' configured, HatchIT has nowhere to send the file and writes nothing.

===== Invoke =====

Run with [[util:JSexec]]. With no options, HatchIT starts in interactive mode:

  jsexec hatchit.js

Supplying any option puts HatchIT in non-interactive mode. To see the usage text:

  jsexec hatchit.js -help

<file>
usage: hatchit.js [option]
options:
  -dir=<filedir>    File directory Internal Code
  -file=<filename>  Name of file to hatch
  -area=<areatag>   File area of file to hatch
  -origin=<FTN AKA> Origin FTN AKA
  -replace[=<mask>] File replaces older version (default mask
                    is the hatched file's own name)

If no option is given, HatchIT will start in interactive mode.
Exit status is 0 on success, 1 on error.
</file>

==== Interactive mode ====

A full-screen menu walks you through the hatch, one prompt at a time:

  - **Select Group** then **Select Dir** then **Select File** - pick the file to hatch from your file bases.
  - **Select Area** - pick the FDN area, from the areas defined in ''[[dir:ctrl]]/tickit.ini''.
  - **Select Origin** - pick which of your FTN addresses (AKAs) the file is announced from.
  - **Replaces (ENTER=none)** - optionally a filename or wildcard mask that this file supersedes (see [[#Replacing an older file]]). Press ENTER to leave it out.
  - **Proceed?** - a summary of the hatch is shown; answer //Yes// to write the TIC and FLO files.

Pressing ESC at any prompt backs out. Escaping all the way out cancels the hatch without writing anything.

==== Non-interactive mode ====

Non-interactive mode is suitable for a timed event, a shell script or a cron job. ''-dir'', ''-file'', ''-area'' and ''-origin'' are all required in this mode.

^ Option ^ Description ^
| ''-dir=<filedir>'' | Internal code of the file directory holding the file. Case-insensitive. Must appear **before** ''-file''. |
| ''-file=<filename>'' | Name of the file to hatch, as it appears in that directory. **Case-sensitive.** |
| ''-area=<areatag>'' | FDN area tag, as defined in ''[[dir:ctrl]]/tickit.ini''. Case-insensitive. |
| ''-origin=<FTN AKA>'' | Which of your FTN addresses the file is announced from. Must be one of your configured AKAs, written exactly as in [[util:SCFG]]. |
| ''-replace'' | The file replaces an older version of the same name. |
| ''-replace=<mask>'' | The file replaces any older file matching the given filename or wildcard mask. |
| ''-help'' | Show the usage text and exit. |

Example - hatch ''NODELIST.Z01'' from the ''fdist-nodelist'' directory into the ''NODELIST'' area, replacing the previous nodelist archive:

  jsexec hatchit.js -dir=fdist-nodelist -file=NODELIST.Z01 -area=NODELIST -origin=1:103/705 -replace=NODELIST.Z*

==== Exit status ====

As of Synchronet v3.22, HatchIT exits with status **0** on success and **1** on error, so a calling script can tell whether the hatch worked:

^ Status ^ Meaning ^
| 0 | The TIC and FLO files were written for every link (or the interactive hatch was cancelled before it began). |
| 1 | An option was invalid or missing, the file/directory/area/AKA could not be found, or one or more links could not be given the file. |

When the status is 1 because a link failed, the reason names the affected address. Run from a command prompt, [[util:JSexec]] writes it to the console; run as a timed event, it lands in your server's console output and log.

===== Replacing an older file =====

Under FTS-5006, a TIC file may carry a ''Replaces'' line naming the file (or wildcard mask) that the new file supersedes. Without it, a receiving TIC processor that already has a file of the same name will refuse the import and log a warning.

  * ''-replace'' uses the hatched file's own name as the mask, which is the common case for a file whose name never changes (a weekly nodelist archive, a daily file list).
  * ''-replace=<mask>'' takes an explicit mask, for a file whose name carries a version or date - for example ''%%-replace=INFO*.ZIP%%'' when hatching ''INFO0725.ZIP''.
  * In interactive mode, the same value is typed at the **Replaces (ENTER=none)** prompt.

The mask is matched against the //hatched// file's name by the receiving system, not against the files it already holds.

===== What gets written =====

For each link configured for the area, HatchIT writes into the outbound directory for that link's zone (and ''.pnt'' directory for a point):

  * A ''.tic'' file naming the area, the origin and destination addresses, the file's name, size, date, CRC and description, the ''Path'' and ''Seenby'' lists, and the link's TIC password.
  * An entry appended to that link's ''.flo'' file referencing the file itself, plus a ''^''-prefixed entry for the TIC (so the mailer deletes the TIC after sending it).

A ''.bsy'' file guards the outbound while the ''.flo'' file is updated, so a hatch is safe to run while a mailer session is in progress.

Long filenames are handled per FTS-5006: the ''File'' line carries an 8.3-style name and, when that differs from the real name, an ''Lfile'' line carries the full name.

===== See Also =====
  * [[:module:|Module index]]
  * [[module:TickIT]] (incoming TIC file processor)
  * [[module:TickITcfg]] (TickIT configuration utility)
  * [[module:BinkIT]] (FidoNet mailer)
  * [[module:addfiles]] (import files into a file directory)
  * [[config:sbbsecho.ini]] (TIC passwords, outbound directory)
  * [[util:EchoCfg]] (SBBSecho configuration utility)

{{tag>fidonet tic tick jsutil}}
