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 - TCP/IP host name or IP address of IBM i 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:\MyFiles\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:

> cd 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:

> cd C:\Users\Public\IBM\ClientSolutions\Start_Programs\Windows_x86-64
> acslaunch_win-64.exe /plugin=logon /system=myibmi /userid=myprofile /password=mypassword
> 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>

The example above 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.

Use the GENERATE_SPREADSHEET scalar function via an SQL interface.
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.
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.

CL 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.

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')

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
 $

Related Information

GENERATE_SPREADSHEET scalar function

IBM i Access - Client Solutions

Using RCVMSG and MONMSG to Retrieve QSHELL Messages

IBM i Access - Client Solutions 5733XJ1

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=.

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z000000cwMLAAY","label":"Data Access-\u003EData Transfer"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Tips

Automating ACS Data Transfer

Question & Answer

Question

Answer

Related Information

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?