SMAFT File Transfer job
- Synopsis
- Full Details
In briefA SMAFT File Transfer job moves a file between two legacy LSAM machines, Windows, UNIX or z/OS. You name a source machine and a destination machine. Start Transfer On then decides which of the two runs the job: the destination pulls (the default), or the source pushes. The job's machine follows from those fields, so Agent Assignment is read-only.
WhereIn Design › Workflows, open a workflow and open the job in the Job Editor (open its context menu on the canvas › Edit Job). On the Job Definition tab, choose SMAFT File Transfer as the job type and set the fields under Job Parameters. A read-only Runs on: line shows which machine will run it. Each machine's FT Role and file-transfer endpoint are set by an administrator on the agent, in Agents › Agents.
WhenUse a SMAFT File Transfer job when:
- a file has to move from one LSAM machine to another;
- the two machines are on different platforms, and line endings should be translated on the way;
- one job should move several files that match a wildcard.
To move files between endpoints on an OpCon MFT agent, use OpCon MFT Transfer. The two job types are unrelated.
How
- Make sure both machines have an FT Role that lets them take part. The default is
None. - Choose the Source Machine and Source File, then the Destination Machine and Destination File.
- Attach a batch user for each end. A UNIX end must have one.
- Set Start Transfer On and the transfer options, then save the job.
For the full steps, see Transfer a file between two LSAM machines.
TextandASCIItranslate line endings, so the byte count can change between platforms. UseBinaryfor an exact copy, and set it on both ends.- A push needs full file-transfer support on both machines.
- With a z/OS machine at either end, Start Transfer On must be
Destination, TLS Required is refused, and EBCDIC is valid on the z/OS end only. A z/OS end takes no batch user. - The job has no exit-criteria setting. The agent's verdict is the outcome.
- A machine with no FT Role set is missing from both machine lists, and a saved job that uses it fails at dispatch.
- If the other machine is unavailable, the job holds, and force-start does not move it.
- A wildcard transfer that involves a UNIX machine needs If File Exists set to
Overwrite, and Compression and Encryption set toNone. - Delete Source File other than
Noneeds both machines to be Windows.
Task walkthrough: Transfer a file between two LSAM machines. This page is the full configuration and troubleshooting reference.
The SMAFT File Transfer job moves a file from one legacy LSAM machine to another using SMA's file-transfer protocol. It is the only job type that names two machines, and the only one whose machine is derived from its own parameters instead of being picked in Agent Assignment.
| Property | Value |
|---|---|
| Job type | SMAFT File Transfer (smaft-file-transfer) |
| Plugin | SMAFT File Transfer (lsam-smaft) |
| Category | File Transfer |
| Runs on | Legacy LSAM agents — Windows, UNIX and z/OS |
| Connections | Up to two batch users, one per end — Windows or UNIX, matching each machine's platform. A z/OS end takes none |
| Relay | Required, like every legacy job type |
Both machines must carry a file-transfer endpoint before a transfer can be built — see Before you can build one.
- Machines and Endpoints
- Configuration
- Rules and Wildcards
- Holds and Outcomes
- Troubleshooting
Machines and Endpoints
The two machines, and which one runs the job
You name a Source Machine (which holds the file) and a Destination Machine (which receives it). Start Transfer On then decides which of the two runs the job:
| Start Transfer On | Direction | The job runs on | Needs |
|---|---|---|---|
| Destination (the default) | Pull — the destination connects to the source and pulls the file | the destination machine | the source's file-transfer server reachable from the destination |
| Source | Push — the source connects to the destination and pushes the file | the source machine | full file-transfer support on both machines |
The other machine — the one that does not run the job — acts as the file-transfer server for that transfer. This page calls it the peer.
The job editor shows the result as a read-only line, so you can see where the job will run — for example Runs on: PAYROLL-WIN (pull — the destination connects to the source and pulls the file).
Because the machine follows from the parameters, Agent Assignment renders read-only and offers no agent pool and no legacy agent group. Change Start Transfer On or either machine and the assignment follows automatically. A transfer is always assigned to one specific machine, and it takes no backup agents: the editor shows no Configure backup agents switch, and a save that sets one is refused — see Which assignments a job type allows.
Once derived, the job behaves like any other specific-agent job: it waits on that machine's availability in the ordinary way, and a long hold there is reported as a long hold. What is different is the peer — see The peer machine holds the job.
Before you can build one
Every machine that takes part in a transfer needs a file-transfer endpoint, configured per agent by an administrator. It is separate from the LSAM host the relay uses, because the two are reached over different network paths: the relay reaches the agent, while for a transfer the peer agent reaches it directly. See File-transfer endpoint for the fields and their defaults.
Two parts of that endpoint gate this job type:
- FT Role decides which pickers a machine appears in.
Source onlyoffers it as a source,Destination onlyas a destination,Both source and destinationas either, andNonein neither. The default isNone— file transfer is opt-in, so a machine takes no part in a transfer until an administrator gives it a role, and no role was backfilled onto agents registered earlier. - Full file-transfer support is what a push requires, on both machines. It defaults to enabled.
A Universal Agent has no file-transfer endpoint and can never take part in a transfer.
When one end is z/OS
A z/OS machine can be the source, the destination, or both. Four rules apply whenever either end is z/OS:
- Start Transfer On must be
Destination. A z/OS end cannot push. The job editor locks the field toDestinationonce either machine is z/OS. - TLS Security cannot be
Required. z/OS file transfer is non-TLS only, so the editor does not offerRequired, andPreferredalways resolves to non-TLS even if TLS is switched on for the z/OS agent. - EBCDIC is available only on the z/OS end. The editor offers it as a data type for an end whose machine is z/OS, and nowhere else. If you change a machine so that a stored value is no longer valid, the editor removes it and shows a note saying why.
- A z/OS end has no batch user. The editor shows z/OS: no connection (sent as N/A) in place of the picker, and any batch user stored for that end is ignored.
These are guides in the editor. The job is checked again when it is dispatched, and a job that breaks a rule fails with a message naming the z/OS machine.
Configuration
Configuration reference
| Parameter | Required | Default | Notes |
|---|---|---|---|
| Source Machine | Yes | — | 1–24 characters. Offered only if its FT role is source or both. |
| Source File | Yes | — | 1–4000 characters, no ". Full path and file name. Wildcards * and ? are allowed — see Wildcard transfers. |
| Source User | No | unset | Batch user on the source machine, picked from your saved connections. Its connection type must match that machine's platform. |
| Source Data Type | Yes | Text | Text, ASCII, Binary, or EBCDIC (only when the source machine is z/OS). |
| Destination Machine | Yes | — | 1–24 characters. Offered only if its FT role is destination or both. |
| Destination File | Yes | — | 1–4000 characters, no ". Full path and file name to write. |
| Destination User | No | unset | Batch user on the destination machine, picked from your saved connections, matching that machine's platform. |
| Destination Data Type | Yes | Text | Text, ASCII, Binary, or EBCDIC (only when the destination machine is z/OS). |
| Start Transfer On | Yes | Destination | Source or Destination. Decides which machine runs the job. Must be Destination when either machine is z/OS. |
| If File Exists | Yes | Do not Overwrite | Do not Overwrite, Overwrite, Backup then Overwrite, Append, or Backup then Append. |
| Delete Source File | Yes | No | No, Required, or Preferred. Anything but No needs both machines to be Windows. |
| Maximum Transfer Rate | Yes | >2048 | Bandwidth cap in kbit/s: 64, 128, 256, 512, 1024, 2048, or >2048. It is a list of fixed steps, not a number — >2048 means uncapped. |
| Compression | Yes | None | Required, Preferred, or None. |
| Encryption | Yes | None | Required, Preferred, or None. |
| Fail If Preferred Settings Not Satisfied | Yes | Off | A switch. Turn it on to fail the job when a Preferred compression, encryption, or TLS setting could not be honored. |
| TLS Security | Yes | Preferred | Required, Preferred, or None. See TLS and the port. Required is refused when either machine is z/OS. |
When you create the job, the editor stores the Default of every field marked Yes that has one, so a new job saved without touching those fields keeps exactly the values the form showed. A required field with no value — one you cleared, or a machine or file you have not set — refuses the save with Required parameter '…' is missing.
Required and Preferred
Compression, Encryption, Delete Source File and TLS Security share a three-way shape:
- Required — the transfer must have it, and fails if the two ends cannot agree on it.
- Preferred — use it if both ends can, otherwise carry on without it. Whether that silent downgrade fails the job is what Fail If Preferred Settings Not Satisfied decides.
- None — do not use it.
Data type
Text and ASCII translate line endings for the receiving platform; Binary does not. EBCDIC is
for a z/OS end and is refused on any machine that is not z/OS. So a text
transfer between platforms can legitimately arrive with a different byte count than it left
with — LF becomes CRLF going to Windows, and CRLF becomes LF going to UNIX. Use Binary when the
file has to arrive byte-for-byte identical.
Binary must be set on both ends. One end streaming raw bytes while the other translates text corrupts the file silently, so a mismatch is refused when you save.
Text works wherever the job runs. Earlier builds rejected it on a transfer whose job ran on a
UNIX machine — the transfer failed on an Unsupported Data Type from that end, with Text being
the default on both ends — so in practice only a Windows-run transfer accepted it. Nothing about the
job needs changing.
The batch user on each end
A transfer authenticates on both machines, so each end takes its own batch user — Source User and Destination User, picked from your saved connections, filtered to the platform of the machine that end names.
| Machine platform | Source User or Destination User left blank |
|---|---|
| Windows | Allowed. The transfer runs as the agent's own service account. |
| z/OS | Not applicable. A z/OS end takes no batch user; the editor shows z/OS: no connection (sent as N/A). |
| UNIX | Not allowed. The job fails when the transfer is built, naming the missing field — UNIX has no service-account equivalent, so a real user and group are needed. |
A UNIX batch user needs both a user and a group, and neither may contain / — the agent
splits the pair on the first slash it finds. See
Connection.
TLS and the port
The port a transfer dials belongs to the peer — it is the machine being connected to — but the TLS switches are checked on both ends, because a TLS handshake needs both halves to speak it.
| TLS Security | Behavior |
|---|---|
| Required | Use TLS. If either machine does not support TLS, or the peer has no TLS port, the job fails. |
| Preferred (the default) | Try TLS; if the pair cannot do it, fall back to the non-TLS port. |
| None | Use the non-TLS port. Fails if either machine does not support non-TLS. |
A z/OS end never takes part in TLS: Required is refused, and Preferred resolves to non-TLS.
If no port can be resolved for the mode you asked for, the job fails naming the machine and the mode, rather than dispatching a transfer that cannot connect.
TLS is fully modeled — the switches, the port pair, and the fallback all behave as described — but it has not been proven on the wire. Non-TLS transfers have been, in both directions, on real Windows and UNIX agents. Treat TLS Security = Required as unverified for now.
Rules and Wildcards
Rules
The rules live at three points, and which point catches a mistake decides what you see.
Refused when you save
These need nothing but the job's own parameters, so the editor refuses the save and names the field:
- Both machines are required.
- Start Transfer On must be
SourceorDestination. - The source and destination must not be the same file on the same machine — there would be nothing to transfer. The same machine with different paths is fine; that is a local copy.
- A Binary data type must be set on both ends.
- The job must be assigned to the machine that runs the transfer. Normally the editor keeps this true for you; a configuration written around the editor — a Code tab edit, an import, or a direct API call — can break it, and this is what catches that.
Fails at dispatch
These need the agent records, so they are checked when the job is dispatched. Each one terminates the job, and the reason is recorded as the job's termination description:
- Either machine is not registered.
- Either machine has no file-transfer configuration — a Universal Agent, for instance.
- The source machine's FT role cannot act as a source, or the destination's cannot act as a
destination. The message names the machine, names its role in words rather than as a protocol
code, and states the role to set — … has file-transfer role 'none' and cannot act as a transfer
source. Set its FT Role to 'source' or 'both' on the agent. Because
noneis the default, this is the most likely reason a first transfer fails on a newly configured platform. - Either machine is z/OS and Start Transfer On is
Source, or TLS Security isRequired, or EBCDIC is set on an end whose machine is not z/OS. The message names the machine. - Start Transfer On = Source and one or both machines lack full file-transfer support. Both offending machines are named at once, so one pass fixes it.
- The peer machine has no file-transfer address.
- No port could be resolved for the TLS mode you asked for.
Checked as the transfer is built
The last group is applied when the job is handed to the agent, and each one fails the job naming the field:
- Binary symmetry, again — a config that reached this point around the editor is still refused.
- A UNIX end has no batch user, or a batch user's type does not match its machine's platform.
- Delete Source File other than
Norequires both machines to be Windows. The UNIX agent hard-fails a delete request. - The wildcard restrictions below.
Wildcard transfers
* and ? in either file name transfer more than one file. When a wildcard transfer involves a
UNIX machine at either end, three settings are constrained:
| Setting | Must be |
|---|---|
| If File Exists | Overwrite |
| Compression | None |
| Encryption | None |
They are checked in that order, and the job fails on the first one that is wrong, naming that field — so set all three before you run it, rather than fixing one per failed run. A wildcard transfer between two Windows machines has none of these restrictions.
Holds and Outcomes
The peer machine holds the job
The machine that runs the transfer is gated on availability like any other assigned agent. The peer is gated too — and differently:
- If the peer is offline, marked offline or draining, or its status cannot be determined because its relay feed has gone stale, the job holds. It is re-evaluated on every scheduling pass and clears by itself when the peer comes back. Nothing terminates and nothing is rerouted.
- Force-start does not bypass this hold, just as it does not bypass the check on the agent a job runs on. That is deliberate: forcing a job whose peer file-transfer server is down cannot succeed, because there is no server to connect to, so bypassing would turn a hold into a certain failure.
Outcomes
The agent's verdict is recorded as it stands. Unlike most legacy job types, a SMAFT job has no exit-criteria setting and none is applied for you — whatever the file-transfer agent reports is the job's outcome.
Because the agent's verdict is trusted verbatim, check that the destination file is what you expect rather than reading success alone.
Troubleshooting
Troubleshooting
| Symptom | Likely cause |
|---|---|
| A machine is missing from the Source Machine or Destination Machine list | Its FT Role excludes that direction, or it is a Universal Agent. A role of None is the default, so a machine nobody has configured is absent from both lists. Roles are per agent — see File-transfer endpoint. |
| The job fails at dispatch saying a machine's file-transfer role cannot act as a source or destination | That machine has no FT Role set, or one that excludes the direction. The message names the role to set. A saved job is not re-checked against the role until it is dispatched, so a job built before the role was set fails here rather than at save. |
| The save is refused naming a field you can see is filled in | Read the message: the two most common are the same-file-on-the-same-machine rule and Binary set on only one end. |
| The job holds indefinitely and nothing is logged as failed | The peer machine is unavailable. It clears when the peer returns; force-start will not move it. |
| A transfer fails with Unsupported Data Type and Transfer failed! | A data type of Text on a transfer whose job ran on a UNIX machine. Fixed — Text is accepted at both ends whichever platform runs the job. If you see it, the platform needs upgrading; changing the job's data type is not the fix. |
| A transfer arrives with a different byte count than the source | Expected on a Text or ASCII transfer between platforms — line endings were translated. Use Binary for a byte-for-byte copy. |
| A job with a z/OS end fails at dispatch naming that machine | z/OS supports Start Transfer On = Destination only, and no TLS Required. EBCDIC is valid only on an end whose machine is z/OS. Change the setting the message names. |
| A push fails naming both machines | Start Transfer On = Source needs full file-transfer support on both. Either enable it on both, or switch to Destination and pull instead. |
| The transfer connects but the credentials are rejected on one end | Each end authenticates separately. Check the batch user attached to that end, and that its type matches that machine's platform. |
| TLS Security = Required fails to resolve a port | One machine does not support TLS, or the peer has no TLS port set. Note that TLS is not verified end to end in this release. |
Contact support when
- A transfer completes successfully but the destination file is wrong or truncated.
- A peer machine reports as available everywhere else but a transfer still holds on it.
- A machine has an FT role and address configured and still reports as having no file-transfer configuration.