OS/400 Agent - File Transfer Support

As an administrator this document will help support you when using file transfers with an OS/400 Agent.

Always start OS/400 Agents v9.00A or later as a multithreaded process to use the new file transfer protocol. This requires the agent's JOBD parameter ALWMLTTHD to be set to YES.

Note: IFS is only supported in combination with the new file transfer protocol.

Important! The new file transfer is handled in threads which includes that you can only use the following file systems:

  • Root (/)
  • QOpenSys
  • User-defined
  • QNTC
  • QSYS.LIB
  • Independent ASP QSYS.LIB
  • QOPT
  • Network File System
  • QFileSvr.400

This page includes the following:

For the new file transfer protocol:

  • The OS commands CRTPF and ADDPFM are used to transfer the files. This means that you can now directly specify the CRTPF parameters in the file transfer's attributes.

  • CRTPF is used to create a file. ADDPFM is processed when a file already exists and you want to add a member.
    An error that occurs in a file transfer that is not clear for AE (such as: "CPF0001 - Error found on ADDPFM command"). This can refer to an error that has occurred while these commands have been processed. In this case, you will find more detailed information in the job log which is directly stored in the OS.

File Specification

QSYS file system

The following syntax applies for file transfers:

Library name/file name(member name)

The wildcard characters * and ? can be used in file and member names. * stands for any number of characters (even no character) and ? for exactly one character.

Important! No member name must be indicated if wildcard characters are used in the file name.

Detailed information about wildcards is provided in the chapter that describes partially qualified file transfers.

For example:

To transfer all file members of TEST:

AE/TEST(*)
or
AE/TEST()

To transfer all file members of TEST whose names start with the letter A:

AE/TEST(A*)

To transfer all file members of TEST whose names consist of 3 characters, start with an A and end on B:

AE/TEST(A?B)

To transfer the file member ABC of TEST:

AE/TEST(ABC)

To transfer all files whose names start with TEST:

AE/TEST*

IFS file system

IFS (Integrated File System) is a UNIX-based file system. IFS files must always be specified with an absolute path (starting from the root) and a final file name.
If the file specification includes a / character, the agent assumes that an IFS file is concerned.

Example:

/home/AE/test.txt

The wildcard characters * and ? can be used to process partially qualified file transfers. They can be used as necessary within the path and/or file name.

In an individual file transfer, the path and file name are not case-sensitive. Therefore, the following two specifications are identical:

/home/AbC.txt
/HOME/ABC.txt

Uppercase and lowercase letters are distinguished in wildcard file transfers. The following two specifications differ from each other:

/home/AB*
/home/ab*

Note: An exception is QOpenSys, here wildcard file event paths are not case-sensitive.

Attributes

Depending on the file system, you can specify all attributes that are supported by OS/400 for the file transfer's destination. Note that you must separate several attributes with a comma. Invalid specifications are ignored.

QSYS file system

The OS/400 Agent is able to transfer the file types *FILE and SAVF. Other ones such as *PGM, *RPG, *CLLE must be collected in SAVF files before they can be transferred. 

The following applies for SAVF file transfers: 

  • Set the attribute reclen=528 in the File Transfer object's source file
  • Select the code page UC_CODE in source and destination file

For all other files, the following applies:

  • If the destination file is not yet available, it will be created. The CRTPF command can be used for this purpose. Therefore, the attributes that can be specified for the file transfer's destination are parameters of this command.
    If no attributes are specified, the file will be created with a record length of 80 bytes (default). In wildcard file transfers, MAXMBRS(*NOMAX) is set by default (this means that the file has no member limit). In individual file transfers, the system's default value is used for MAXMBRS.
  • If the destination file already exists, its attributes can only be overwritten if the option "Keep original file attributes" is set in the File Transfer object. The CHGPF command is used for this purpose. You can specify its parameters as the destination attributes in the File Transfer object.

You can use the option Keep original file attributes in the File Transfer object in order to transfer the source's file attributes for the destination file(s). Doing so requires the source and destination agent to have the same operating system (in this case OS/400) and Automation Engine v9.00A (or later). Otherwise, this setting will be ignored.

The following file attributes can be transferred:

  • ACCPTHSIZ - Access path size
  • ALWUPD - Allow update operation (ALWUPD). If on, records are not allowed to be updated in the file (*NO).
  • ALWDLT - Allow deletion operation (ALWDLT). When active, records cannot be deleted from the file (*NO).
  • CCSID - Coded character set ID
  • EXPDATE - Expiration date for member
  • FRCACCPTH - Force keyed access path
  • FRCRATIO - Records to force a write
  • LANGID - Language ID
  • MAINT - Access path maintenance
  • MAXMBRS - Maximum members
  • PAGESIZE - Access path logical page size
  • RCDLEN - Record length, if no DDS, DDS contains the full record format (keys, fields, relations, etc.)
  • REUSEDLT - Reuse deleted records
  • SHARE - Share open data path
  • SIZE - Member size, initial number of records, increment number of records, maximum increments
  • TEXT - Text 'description'

The parameter order is irrelevant.

Example

This example creates a file with a record length of 256 bytes and enters the text 'FT File' as a description:
RCDLEN(256) TEXT('FT File')

The second example creates a file with a maximum number of members without a size limit and reuses deleted records:

MAXMBRS(*NOMAX) SIZE(*NOMAX) REUSEDLT(*YES)

Additionally, you can use the specific parameter TRIM=YES in the Attributes field of the file transfer's source. This option is not a real file attribute but a UC4-specific function. It automatically removes blanks that are used at the beginning and end of each line of the files that should be transferred. This option cannot be used in combination with the IFS file system.

Additionally, you can use the specific parameter TRIM=YES in the Attributes field of the file transfer's source. This option is not a real file attribute but an AE-specific function. It automatically removes blanks that are used at the beginning and end of each line of the files that should be transferred. This option cannot be used in combination with the IFS file system.

IFS file system:

The following two original IFS file attributes can be used in the destination file(s):

  • ccsid - The CCSID used for the data in the file or the extended attributes of the directory.
  • codepage - The code page derived from the CCSID used for the data in the file or the extended attributes of the directory.
  • readonly - Determines whether a read-only file is created.

The following example creates a file with the codepage (ccsid) 550 which has the attribute READ-ONLY:

ccsid=550, readonly=YES

IFS: You can also pass the attributes of the original file on to the target file provided that this is defined in the File Transfer object. The attributes readonly, hidden, system and archive can also be used across platforms or from Windows files. You can also override these attributes when you specify the target file. The attributes ccsid and codepage only apply to OS/400 files.