The CopyWrite File Transfer Service provides a way of copying native A_Series files between A-Series host computers, using transport services such as TCP/IP.
It is made up of two parts. The CopyWrite Library, which provides the interface to the MCP LIBRARY/MAINTENANCE module, and a CopyWrite Bridge, which implements the connection between the remote hosts, using protocols such as BNA and TCP/IP, or some other connectivity service such as HY.
CopyWrite selects the CopyWrite Bridge to be used, through the association of a WFL protocol with a CopyWrite Bridge InterfaceName.
A WFL protocol name is specified in a COPY statement, for example, COPY [FTAM]... FTAM is the WFL protocol name. Other protocol names that may be used with CopyWrite are NFT and HS.
The association between a WFL protocol name and a CopyWrite Bridge InterfaceName is defined in a MAGUS configuration variable called COPYWRITEPROTOCOL.
For example, COPYWRITEPROTOCOL=FTAM=TCPIP.
When a remote file transfer COPY statement is executed in WFL, MAGUS checks whether a protocol has been specified. If a protocol has been specified, and the protocol name appears in the COPYWRITEPROTOCOL list, the COPY statement is passed to CopyWrite, along with the COPYWRITEPROTOCOL configuration variable.
CopyWrite then uses the association FTAM=TCPIP, in the example above, to link to a connection library, with an InterfaceName of TCPIP in the system library SL=COPYWRITETCPIP.
This is the mechanism by which CopyWrite can use different connectivity services for transporting the data between remote hosts.
The CopyWrite Bridge that uses TCP/IP is contained in the codefile,
*METALOGIC/COPYWRITE/BRIDGE/TCPIP
It implements an interface called TCPIP.
The codefile must be marked as TASKING, because on the remote host, it assumes the usercode specified by an RU entry. The codefile should have already been so marked, but if not this ODT command may be used,
MP *METALOGIC/COPYWRITE/BRIDGE/TCPIP on <family> + TASKING
It must be installed as a system library,
SL COPYWRITETCPIP=*METALOGIC/COPYWRITE/BRIDGE/TCPIP on <family>
It should be installed as a DSS, so that an incoming request for file transfer services will initiate the library. When the library codefile is run as a program, under a privileged usercode, it registers the DSS called COPYWRITETCPIP.
RUN *METALOGIC/COPYWRITE/BRIDGE/TCPIP on <family> For Example, Run *Metalogic/Copywrite/Bridge/Tcpip #RUNNING 01837 #1837 Metalogic CopyWriteTCPIP Version 45.450.05 was compiled at 17:37:56 on the 24th January 2000 (MCP 45.131.1358) #1837 Loading DSS Commands in (USER)COPYWRITETCPIP/DSS/COMMANDS ON SUPPORT #1837 PK132 (USER)COPYWRITETCPIP/DSS/COMMANDS REMOVED ON SUPPORT #1837 Endpoint Name: COPYWRITETCPIP, Public Endpoint: TRUE #1837 Filename: COPYWRITE, Applicationgroup: #1837 Myname: "22256" #1837 DSSname: COPYWRITETCPIPDSS, Class: OTHER #1837 Recovery after Halt/Load: TRUE, Initialize DSS: TRUE #1837 Endpoints: COPYWRITETCPIP #1837 Provider name: COPYWRITETCPIP, Task type: NonMonitoredSupportLibrary #1837 Interface: None #1837 SL: COPYWRITETCPIP #1837 DSSes provided: COPYWRITETCPIPDSS
If OPTIONS=DEBUG is label equated, the configuration file used to register the DSS is not removed, and can be manually loaded using this command,
NA LOAD <filename>
If the program is run under a non privileged usercode, the configuration file is created, but is not loaded.
The association between a WFL protocol and an InterfaceName is specified in the MAGUS configuration variable called COPYWRITEPROTOCOL.
The syntax for this variable is,
COPYWRITEPROTOCOL=<association list>
<association list>::= <association> | <association> , <association list>
<association> ::=<protocol association>
<protocol association>::=<WFL protocol name>=<interfacename>
<WFL protocol name> ::= FTAM | NFT | HS| NONE
<interfacename> ::= {alphanumeric identifier}
The variable is set using META/INSTALL.
For Example, U Meta/Install COPYWRITEPROTOCOL=FTAM=TCPIP,NFT=BNA,HS=HY #RUNNING 01839 #? #1839 INSTALL:Variable COPYWRITEPROTOCOL set to FTAM=TCPIP,NFT=BNA,HS=HY #ET=1.5 PT=1.2 IO=0.1
The current value of this variable can be interrogated using META/INSTALL.
For Example, U Meta/Install COPYWRITEPROTOCOL #RUNNING 01838 #? #1838 INSTALL:Variable COPYWRITEPROTOCOL = FTAM=TCPIP,NFT=BNA,HS=HY #ET=1.5 PT=1.0 IO=0.1
Normally, if a protocol is not specified in a WFL COPY statement, the statement is passed to DSS, which selects a file transfer service based on the networks and services available between the hosts.
CopyWrite can be made the default file transfer service when an explicit or implicit protocol has not been specified. An explicit protocol is set using theCOPY [<protocol>] syntax. An implicit protocol is set by WFL when it detects attributes suchasIPADDRESS forFTP, or DOCUMENTTYPE for FTAM, which are only available with a specific protocol.
If CopyWrite is to be used as the file transfer service when a protocol is not specified in a WFL COPY statement, a <protocol association> of NONE=<interfacename> may be specified.
For Example,
U Meta/Install COPYWRITEPROTOCOL=FTAM=TCPIP,NFT=BNA,HS=HY,NONE=TCPIP #RUNNING 01839 #? #1839 INSTALL:Variable COPYWRITEPROTOCOL set to FTAM=TCPIP,NFT=BNA,HS=HY,NONE=TCPIP #ET=1.5 PT=1.2 IO=0.1
A COPY statement which does not specify a protocol, and which does not involve a source or destination volume which is a CDROM, will use the TCPIP transport to copy the file to or from the remote host, and so behaves as if COPY [FTAM] had been specified.
If a COPY statement specifies a CDROM volume as either a source or a destination, then CopyWrite assumes that the COPY statement is a local CDROM copy request. If a COPY statement should copy to or from a CD Image on a remote host, then an explicit protocol must be used (to resolve the ambiguity between a local and a remote CDROM request, when both must specify a HOSTNAME, and the HOSTNAME is either the remote A-Series Host, or a dummy host used to enter CopyWrite, or a non A-Series Host used with the AUTOUNLOAD feature).
This feature provides a way for predefined actions to be performed after a copy has completed.
These actions may include starting a WFL job.
An FTAM COPY statement in WFL may specify a DOCUMENTTYPE attribute for each element in the file selection list. The valid DOCUMENTTYPEs areFTAM1, FTAM2, FTAM3 andINTAP1.
For example, COPY [FTAM] MYJOB(DOCUMENTTYPE=FTAM1) TO DISK(HOSTNAME=DEVELOPMENT)
COPYWRITE has predefined actions associated with these DOCUMENTTYPEs.
| Type | Action | Description |
|---|---|---|
| FTAM1 | START | If the file is found, and it has a FILEKIND of JOBSYMBOL, it is started. |
| FTAM2 | - | No action defined |
| FTAM3 | - | No action defined |
| INTAP1 | - | No action defined |
A DOCUMENTTYPE is usually associated with a file in a COPY statement, however, it may also be associated with a directory. The file and directory list in the COPY statement is a selection expression, which Library/Maintenance uses to select files. If the COPY statement has completed successfully, COPYWRITE creates a list of the files copied. For each file in the list, it applies the selection expression from the COPY statement. If an element in the selection expression selects the file, and it has an associated action, the action is performed on the file, otherwise the next element in the selection expression is applied.
If an IPADDRESS is specified on a WFL COPY statement, WFL unconditionally sets the protocol to FTP. Therefore, IPADDRESS cannot be used with COPYWRITE, and the remote host must be specified by HOSTNAME.
For Example,
COPY [FTAM] T TO DISK(HOSTNAME=DEVELOPMENT)
The TCP/IP Bridge sets the YOURHOST attribute of the port subfile to the HOSTNAME value, and attempts to establish a connection. The MCP OPEN function searches the TCP/IP Mapping Table for a matching entry, and if not found, it uses RESOLVER to resolve the name using Domain Name Services (DNS).
A hostname entry may be added to the TCP/IP Mapping Table using the ODT command,
NW TCPIP MAPPING + <hostname><ipaddress>,<ipaddress>...
For Example,
NW TCPIP MAPPING + DEVELOPMENT 192.168.16.2 Response: DEVELOPMENT MAPPED TO 192.168.16.2
See the Network Administrator for use of RESOLVER and a DNS.
A file transfer to a remote host must have a usercode.
If the COPY is initiated without a usercode, such as from an ODT, the system HU is used, otherwise the initiators usercode is used.
The usercode is sent to the remote host along with the connection request.
The TCP/IP Bridge at the remote host uses the usercode to search in turn for the entry RU <usercode> OF *IPADDRESS <ipaddress>, RU <usercode> OF <hostname> and RU <usercode> OF *DOMAINNAME <domain name>. If a matching entry is not found, the connect request is rejected.
If the entry is found, then the usercode, or it's alias if specified, is the usercode under which the Copy will be performed by LIBRARY/MAINTENANCE on the remote host. The usercode specifies the default settings, such as Family Substitution, and any limits for the Copy.
This security is independent of the security facilities provided by the TCP/IP Service Provider. See the Security Features Operating and Programming Guide, Restricting System Access from TCP/IP Requests.
An RU entry is added to the USERDATAFILE using the *SYSTEM/MAKEUSER utility.
For Example,
+RU APPLE OF *IPADDRESS 192.168.16.2 LOCALALIAS=POMME; << Entered RU APPLE OF *IPADDRESS 192.168.16.2 LOCALALIAS=POMME +RU APPLE OF *DOMAINNAME ftp.local.lu; << Entered RU APPLE OF *DOMAINNAME FTP.LOCAL.LU +RU APPLE OF SPRING; << Entered RU APPLE OF SPRING
See the Security Administration Guide, Section 10 Using SYSTEM/MAKEUSER,"Identifying Users from Remote Hosts" for further information.
When a remote file transfer is initiated, several tasks are started, including one called *FILE/TRANSFER/SERVICES
A <mixno>HI issued to this task will display the current file being copied, and the percentage of the file copied.
For example,
?1856HI
#1856 <1> (USER)T 100% copied. Record 1 of 1
A response to the HI will only be issued while a file is being copied.
When the TCP/IP Bridge is started on the source host it provides a number of client connections, since there may be several simultaneous Copy statements executing. If there are no available client connections, COPYWRITE cannot connect, and the Copy statement is terminated.
A <mixno>HI 60 issued against the TCP/IP bridge connection library stack will display the status of the client connections.
When the TCP/IP Bridge is started on the destination host, it offers a number of TCP/IP port subfiles for incoming requests from remote hosts. These subfiles have a FILENAME of COPYWRITE_AGENT.
Theses connections can be seen by issuing this command,
NW TCPIP CONN FILENAME COPYWRITE_AGENT
A <mixno>HI 70 issued against the TCP/IP Bridge connection library stack will display the status of the Agent connections.
Files may be copied from a single source volume to a single destination Tape volume at a remote host. (Note, this restriction is imposed by Library/Maintenance).
When the COPY request is received at the remote host, Library/Maintenance requests that a tape be mounted. A waiting entry appears, and Library/Maintenance waits.
The dialog between the source host and the destination host is conducted over a network, and the dialog protocol requires acknowledgements for certain types of information within a certain timelimit. If the acknowledgement is not received, the dialog is terminated and the COPY is discontinued.
If a tape is not mounted within the dialog acknowledgement timelimit, the COPY statement is terminated.
The default timelimit for a copy to Tape is currently set to 5 minutes. This may be changed by setting a WAITLIMIT on the COPY statement. The timelimit is set to the maximum of the default timelimit and the WAITLIMIT.
When a tape reel is filled, the Tape is rewound, and Library/Maintenance requests that the next reel be mounted. A waiting entry appears, and Library/Maintenance waits. This wait is handled in the same way as the initial tape mount.
Some of these limitations may be removed in later releases.
Install
COPYWRITE on the source and destination hosts.
Install TCP/IP
Bridge on the source and destination hosts.
Associate
a WFL protocol with the InterfaceName TCPIP in the
MAGUS variable COPYWRITEPROTOCOL.
Establish
an NW TCPIP MAPPING for the remote host.
Add an
RU entry at the remote host.