IBM Support

Automating ACS Data Transfer

Question & Answer


Question

How do you automate data transfer requests when you use IBM i Access Client Solutions (ACS)?

Answer

IBM i Access Client Solutions (ACS) provides plug-ins for both data transfer downloads and data transfer uploads. The plug-ins are available as part of the IBM i Access Client Solutions deployment on the platform.  They are documented in the GettingStarted document in the ACS documentation folder under "Advanced Topics," section 9.1 "More command-line Options."  See sections 9.1.15 (Download) and 9.1.16 (Upload).

These plug-ins can be used to run saved data transfer requests in batch without having the ACS client open. To run the requests without any user intervention, with the transfer request open click the Properties button, go to the Startup tab, and check the boxes on "Run transfer request automatically" and "Close on completion".

The options available are as follows:

Download

/PLUGIN=download [/userid=<userid>] <filename> [ <filename> <filename> ...]
  • userid - user ID to use to connect to the target system.
  • <filename> - file with the dtfx extension that was created from a previous Data Transfer download.  Multiple files can be specified with or without this keyword.

The download plug-in enables the user to run a previously saved Data Transfer download.

Upload

/PLUGIN=upload [/userid=<userid>] <filename> [ <filename>  <filename> ...]
  • /userid - user ID to use to connect to the target system.
  • <filename> - file with the dttx extension that was created from a previous Data Transfer upload.  Multiple files can be specified with or without this keyword.

The upload plug-in enables the user to run a previously save Data Transfer upload.
Provide credentials to prevent prompting
If you are automating the transfer, you probably don't want to be prompted for credentials.  To make that work, you need to use the logon plug-in before you run the data transfer plug-in.
The syntax for the logon plug-in is:
/PLUGIN=logon /SYSTEM=<system> [/USERID=<userid>] [/PASSWORD=<password>] [/AUTH] [/C] [/GUI=<1|0>]
  • /SYSTEM   - name of system
  • /USERID   - user ID
  • /PASSWORD - password associated with the user ID
  • /AUTH     - attempts connect to system with specified logon credentials and caches them only on success
  • /C        - clears the cache
  • /GUI      - whether or not a graphical user interface can be used

The following is an example of running a data transfer download request from a Windows command line:

java -jar C:\Users\Public\IBM\ClientSolutions\acsbundle.jar /plugin=download C:\Users\Public\Documents\testacs.dtfx
  • Specify the path to the location of the acsbundle.jar
  • Specify the path to your dtfx save transfer request
  • User /userid=<yourid> if wanted
  • For batch or unattended transfers, redirect success or failure message output by adding ">> C:\TransferResults.log" or similar to the end of the command.
Alternatively, the launcher could be used instead of invoking Java directly:
C:\Users\Public\IBM\ClientSolutions\Start_Programs\Windows_x86-64\acslaunch_win-64.exe /plugin=download C:\testacs.dtfx
To prevent the transfer from prompting for a user ID, use two consecutive commands that use the logon and data transfer plug-ins:
C:\Users\Public\IBM\ClientSolutions\Start_Programs\Windows_x86-64\acslaunch_win-64.exe /plugin=logon /system=myibmi /userid=myprofile /password=mypassword
C:\Users\Public\IBM\ClientSolutions\Start_Programs\Windows_x86-64\acslaunch_win-64.exe /plugin=download /userid=myprofile C:\testacs.dtfx

Note in this previous example, the value provided for the "/system" parameter must match the system name used in the data transfer request file.
An example of running a data transfer upload would be similar:

java -jar C:\Users\Public\IBM\ClientSolutions\acsbundle.jar /plugin=upload C:\testacs.dttx

These commands can also be placed in a PC batch file.
Here is a sample VBA macro that automates running a saved download:
  
Public Sub ACSDownload()
    Dim strPgm As String
    Dim strArg1 As String
    Dim strArg2 As String
    Dim strArg3 As String
    Dim strArg4 As String

    strPgm = "java"
    strArg1 = "-jar"
    strArg2 = "C:\Users\Public\IBM\ClientSolutions\acsbundle.jar"
    strArg3 = "/plugin=download"
    strArg4 = "C:\Users\IBM_ADMIN\Documents\IBM\iAccessClient\DataTransfer\downloadQcustcdtToExcel.dtfx"

    Call Shell("""" & strPgm & """ """ & strArg1 & """ """ & strArg2 & """ """ & strArg3 & """ """ & strArg4 & """", vbHidden)
End Sub


The plug-ins can be initiated from an IBM i command line when there is an existing PC5250 telnet session:

For example,:
===> STRPCO <enter>
===> STRPCCMD PCCMD('C:\Users\Public\IBM\ClientSolutions\Start_Programs\Windows_x86-64\acslaunch_win-64.exe /PLUGIN=download
C:\Users\IBM_ADMIN\Documents\IBM\iAccessClient\DataTransfer\simple.dtfx') <enter>

This example assumes a copy of acslaunch_win-64.exe is in the default 'all-users' deployment path and "simple.dtfx" exists.

The following also works (if jar files are associated in windows to launch with a valid java runtime):
===> STRPCCMD PCCMD('C:\Users\Public\IBM\ClientSolutions\acsbundle.jar /PLUGIN=download
C:\Users\IBM_ADMIN\Documents\IBM\iAccessClient\DataTransffer\simple.dtfx')

...but provides less feedback in the Windows command/DOS window that pops up.


ACS Data Transfer directly on the IBM i:
Another option to automate ACS data transfer would be to run the transfer directly on the IBM i.
This option would eliminate the need to use STRPCCMD or RUNRMTCMD.
The downloaded file can then be sent or moved directly from an IFS directory by using QNTC, SFTP, mail, or another option.

Following are a few ways that you can automate ACS data transfer directly on the IBM i.
  1. Automating this option can be done by placing the acsbundle.jar file in an IFS directory on the IBM i. The following example shows the acsbundle.jar in a user's home directory.

    Here is an example of the commands that can be run on the IBM i to download a file to an IFS directory:

     ===> JAVA CLASS('/QIBM/ProdData/Access/ACS/Base/acsbundle.jar') PARM('/PLUGIN=logon' '/SYSTEM=myIBMi' '/USERID=myUSRPRF' '/PASSWORD=xxxxxxx')
    ...and then:
     ===> JAVA CLASS('/QIBM/ProdData/Access/ACS/Base/acsbundle.jar') PARM('/PLUGIN=download' '/USERID=myUSRPRF' 'testdt.dtfx')

    The dtfx must be created previously with the "Output device:" of File and the Name: being a path in the IFS where the file is downloaded to. The file can be created as a specific file type or format as specified when you create the dtfx.
     
  2. Normally, the reason someone runs ACS data transfer on the IBM i is that they want to automate it in a batch process. In that case, we recommend using Qshell instead of RUNJVA because you will not have to interact with the screen after every step.

    Here is an example of running a download followed by the kill daemon maintenance utility to kill the extra JVM:
     PGM
       qsh cmd('java -jar /QIBM/ProdData/Access/ACS/Base/acsbundle.jar +
               /plugin=DOWNLOAD /home/myUSRPRF/testdt.dtfx;
         java -jar /QIBM/ProdData/Access/ACS/Base/acsbundle.jar +
         /plugin=MAINT /KILLDAEMON')
    ENDPGM

    Unless you are intending for the transfer to run under a different user than the job is running under, you do not need to specify the userid and password. Java toolbox connects by using the user of the current job when the user ID and password are not specified. You also need to run the kill daemon plug-in to end the password cache JVM.

    As in the previous example, the acsbundle.jar and the dtfx saved data transfer request are stored in the user's home directory in the IFS.
     
  3. This example runs a data transfer as the current user of the job on the local system and creates an Excel XLSX file with the column heading text as column headings:

     ===> JAVA CLASS('/QIBM/ProdData/Access/ACS/Base/acsbundle.jar') PARM('/plugin=cldownload' '/system=localhost' '/hostfile=QIWS/QCUSTCDT' '/clientfile=/tmp/custdata.xlsx' '/colheadings=1' '/usecollabels')
     
  4. This example runs in a shell (QShell or PASE) and transfers any number of files using the CLDOWNLOAD plugin. This technique uses two files. First a text file that lists the library/file(member) name to be transferred, some whitespace (spaces or tabs) and the path and name of the file to transfer to. I named this file /mikswens/files.txt. Following are the contents of this file:

    mikswens/myclsrc /tmp/aamyclsrc.txt             
    mikswens/mycsrc /tmp/aamycsrc.txt               
    mikswens/qcustcdt /tmp/cust.txt                 
    mikswens/myrpgsrc /tmp/myrpgsrc_first_member.txt
    mikswens/myrpgsrc(getsves) /tmp/getsves.rpg.txt 

    The work is done by the following simple script that reads the contents of files.txt in a for loop, assigning the first string to variable f1 and the second string to variable f2 and substituting those variables into a call to the acsbundle.jar cldownload plugin. I added a call to the date function to show how this actually runs quite quickly, much faster than making 5 separate invocations to start java:

    date
    while read f1 f2; do
      java -jar /QIBM/ProdData/Access/ACS/Base/acsbundle.jar /plugin=cldownload /system=localhost /hostfile=$f1 /clientfile=$f2
    done < /mikswens/files.txt
    date

    The following is the output of running the script:
    > xferfiles.sh
      Fri Jun 21 14:22:00 Central Daylight Time 2024
      Transfer request is complete.
      Transfer statistics: 00:00:00
      Rows transferred: 8
      Transfer request is complete.
      Transfer statistics: 00:00:00
      Rows transferred: 18
      Transfer request is complete.
      Transfer statistics: 00:00:00
      Rows transferred: 12
      Transfer request is complete.
      Transfer statistics: 00:00:00
      Rows transferred: 45
      Transfer request is complete.
      Transfer statistics: 00:00:00
      Rows transferred: 183
      Fri Jun 21 14:22:38 Central Daylight Time 2024
     $
Note the IBM i Access Client Solutions client is now delivered by PTF and can be deployed to the IBM i itself by installing the PTF on IBM i.  The current PTF levels at the time of the latest update to this document are:
  5770SS1 V7R5M0 SI84315
  5770SS1 V7R4M0 SI84313
  5770SS1 V7R3M0 SI84314
The path to which the client is deployed by the PTF: /QIBM/ProdData/Access/ACS/Base.

See the GettingStarted documentation shipped with the ACS client or available at:
ftp://ftp.software.ibm.com/as400/products/clientaccess/solutions/GettingStarted_en.html

Example data transfer from IBM i request - save following text into file /home/myUSRPRF/testdt.dtfx:
[DataTransferFrom]
DataTransferVersion=1.0
[HostInfo]
Database=*SYSBAS
HostFile=qiws/qcustcdt
HostName=localhost
[ClientInfo]
OutputDevice=2
FileEncoding=UTF-8
ClientFile=/home/myUSRPRF/testdata.xlsx
CrtOpt=1
ClientFileType=23
SaveFDF=0
FDFFile=
[SQL]
Select=*
[Properties]
Convert65535=1
StoreDecFAsChar=1
Notify=1
DisplayLongSchemaNames=1
DisplayLongTableNames=1
DisplayLongColumnNames=1
SQLStmt=0
UserOption=0
UseSSL=2
[Options]
DateFmt=MDY
DateSep=[/]
TimeFmt=HMS
TimeSep=[:]
DecimalSep=.

[{"Product":{"code":"SWG60","label":"IBM i"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Component":"Access Client Solutions","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"Version Independent","Edition":"Standard","Line of Business":{"code":"LOB68","label":"Power HW"}}]

Document Information

Modified date:
21 June 2024

UID

nas8N1020552

Page Feedback