Referencing

openFT-Script also allows you to combine context objects.
For example, a partner (see section “partner”) does not have to be specified in full at every location. You can transfer a partner to a context object and re-use it via referencing.

The following rules apply to de-referencing:

1. A ref attribute references a context object with the specified ID and the object type of the context object (e.g. file, partner).

2. The search is continued in the parent context if no suitable object is found in the current object. If no suitable context object is found there then the search is continued in its parent context.
   Multi-level referencing is permitted.

3. If no suitable context object is found then the script is terminated with the error ft_reference (see section “Error handling”).

4. ref="A" is permitted in a context object with ID="A". In this case,
   ref always refers to the parent context.

5. Circular references are nor permitted:

   obj1(ID="A", ref="B"); obj2(ID="B", ref="A") is not possible in one and the same context. The error ft_reference is output.

6. All the attributes and elements of the referenced element which are not present in the referenced element are taken over. Before being taken over, the referenced element is de-referenced on the basis of these rules.

Examples

1. Valid referencing

 <?xml version="1.0" encoding="UTF-8"?>
 <ftscript version="1">
   <context>
     <partner id="remote" name="WindowsP_1">
       <transferAdmission>
         <ftacAdmission ftacAdmission="FTACADM"/>
       </transferAdmission>
     </partner>
     <file id="pack" name="pack1.bin">
       <partner ref="remote"/>
       <directory name="frg_eis_01"/>
     </file>
   </context>
   <transferFile>
     <fromRemoteFile ref="pack"/>
     <toLocalFile name="pack1.bin">
       <directory name="frg_eis_01"/>
     </toLocalFile>
   </transferFile>
   <transferFile>
     <context>
       <partner id="remote" name="UnixP_1">
         <transferAdmission>
           <ftacAdmission ftacAdmission="FTACADM"/>
         </transferAdmission>
       </partner>
     </context>
     <fromRemoteFile ref="pack">
       <partner ref="remote"/>
     </fromRemoteFile>
     <toLocalFile name="pack2.bin">
       <directory name="frg_eis_01"/>
     </toLocalFile>
   </transferFile>
 </ftscript>

The file object with the ID="pack" references a partner object with ID="remote". The partner WindowsP_1 is used in the first transferFile activity.

The same file object pack is referenced in the second transferFile activity. However, the partner has been overwritten. Consequently, the partner UnixP_1, which is defined in the context of the second transferFile, is addressed. This definition hides the Windows partner with Id="remote".

If the partner was not overwritten then the Windows partner would be used since this is found in the pack object definition in the ftscript context. The partner (on the Unix system) from the context of the second transferFile would be ignored since it is no longer accessible from the definition Id="pack".

2. Invalid referencing

 <?xml version="1.0" encoding="UTF-8"?> 
 <ftscript version="1">
   <transferFile>
     <fromRemoteFile ref="pack"/>
     <toLocalFile name="pack1.bin">
       <directory name="frg_eis_02"/>
     </toLocalFile>
   </transferFile>
 </ftscript>

The pack reference is not defined. The script outputs an error ft_noRef. This is not processed (no faulthandler defined). The script is terminated before execution of the transferFile activity. No restart is possible. You can use ftshws to display the reason for termination.