attrib - UDM Command

Syntax

attrib logical-name[={dd|dsn|hfs|lib}]

[attribute-name=[attribute_value]]...


Description

The attrib command sets the file system attributes that govern the transfer operations on the host with the specified logical name.

If only a logical name is specified in the attrib command, the current set of attributes for the specified host is displayed. For systems that support multiple file systems, such as z/OS and IBM i, the logical name can be followed by an file system name that indicates the files system to which the attribute applies:

  • z/OS: hfs, dsn, dd
  • IBM i: hfs, lib

If no file system name is specified, the attributes will be applied for the currently selected file system. If no attributes are specified, the transfer server returns its current set of attributes and their values.

Parameters

Parameter

Description

logical-name

Logical name of the transfer server for which to set the attributes (or from which to retrieve the attributes).

dd|dsn|hfs|lib

File system for which the attribute is to be set:

  • Values dd and dsn are valid only on z/OS file systems.
  • Value hfs is valid only on z/OS and IBM i file systems.
  • Value lib is valid only on IBM i file systems.

If no file system is specified, the attribute is set for the current file system on the specified server.

attribute-name

Name of an attribute.

attribute-value

Value to be set for the attribute.

Common File System Attributes

The following attributes are common to UDM on most platforms.

Attribute Name

Values

Description

asa

yes, no

Note

This attribute is used only for UDM for z/OS, when using the dd or dsn file system.

 
Specifies whether American Standards Association (ASA) print control characters are translated for data sets whose record format includes an A (for example: FA, FBA, VBA).

  • If value is yes, UDM translates ASA control characters based on rules documented in the zOS XL C/C++ Programming Guide.
  • If value is no, UDM performs no translation.


Default is no.
 
For more information regarding UDM handling of ASA text files, see UDM - Copying ASA Text Files - z/OS.

bom

default, yes, no

Controls byte order mark (BOM) processing for UTF16-encoded output files.
 
When a file is written using one of the UTF-16 encodings - UTF-16, UTF-16LE, or UTF-16BE - the bom attribute specifies whether or not a byte order mark (BOM) should be included at the start of the output file.
 
If the value of bom is default, then the conversion routines decide whether or not a BOM is included in the output file. This value is provided for compatibility with the UDM 6.2.0 release, which introduced UTF-16 conversions, but did not provide BOM handling.
 
The behavior when bom=default is:

  • All platforms, other than AIX

    If the destination file's codepage is UTF-16, a BOM is included with the output file.

    The output file receives a BOM that matches the default encoding of the system upon which the file is created.

    For example, a file created on an Intel-based architecture will have a little endian (LE) encoding and will receive a BOM of U+FFFE. Likewise, a file created on a z/OS system will have a big endian (BE) encoding with a BOM of U+FEFF.

    If the destination file's codepage is UTF-16LE or UTF-16BE, no BOM is included.


  • For AIX

    No BOM is included in the output file. If the output file's codepage is UTF-16, it will have a big endian (BE) encoding.

    A file with little endian (LE) encoding may be created on an AIX system by using a codepage of UTF-16LE.


If the value of bom is yes, then a BOM is always included in the output file. The type of BOM a file receives depends on its codepage value.

  • UTF-16: A BOM that represents the default encoding of the system upon which the output file is created included with the file.
  • UTF-16BE: The output file will have a big endian (BE) encoding and a BOM of U+FEFF is included in the output file, regardless of the system upon which the file is created.
  • UTF-16LE: The output file will have a little endian (LE) encoding and a BOM of U+FFFE is included in the output file, regardless of the system upon which the file is created.


If the value of bom is no, a BOM is never included in the output file.
 
The default value is default.

casesensitive

yes, no

Controls how forfiles wildcard variable expansion is processed. The value should match how the forfiles file list was generated on the target UDM server; in most cases, that will be true. However, Windows has some unique casing scenarios; for example, it is possible for the file system to be mostly case insensitive while one or more specific directories are case sensitive.
 
The casesensitive attribute is associated with the file system; its default value is set based on the file system type:

  • UNIX: yes
  • WINDOWS: no
  • DD: no
  • DSN: no
  • HFS: yes

createop

append, new, or replace

Specification for how the file is to be created:

  • If value is append, the transferred data is appended to any data already in an existing destination file. If the destination file does not exist, it is created.
  • If value is new, the UDM copies the file only if the destination file does not already exist. If the destination file does exist at the time the copy operation is initiated, the operation returns with an error.
  • If value is replace, UDM overwrites an existing destination file. Otherwise, UDM creates the file.

Default is new.

defext

Any sequence of characters valid for the destination file system.

Sequence of characters appended to the end of the filename used to write the destination file, if the source filename is being used implicitly as the destination filename. This occurs after the file extension has been truncated (if truncext is set to yes).
 
By default, no default extension is defined.


Note

The sequence of characters is appended verbatim. UDM does not add a dot character before the sequence, so if one is desired, it must be specified explicitly.

eol

Any sequence of valid text data.

End-of-line sequence used in text transfers.
 
For the source side of a copy operation, excepting those from the z/OS dd and dsn file systems and the IBM i lib file system, the end-of-line sequence is used to determine the end of each line of data. When the specified sequence occurs in the data, UDM considers all data read up to that point (starting from the previous line) as a single line. Each line is transferred without the end-of-line sequence.
 
On the destination side of a text transfer, the end-of-line sequence is appended to the end of each line before it is written.
 
Two special character sequences can be used in any end of line sequence:

  • \r sequence indicates a carriage return.
  • \n sequence indicates a line feed.vv


 
Default depends on the platform and the file system:

  • Under Windows, the default is \r\n.
  • For UNIX platforms and the HFS file system under USS, the default value is \n.
  • Under z/OS (for the dd and dsn file systems) and IBM i (for the lib file system), the eol attribute is undefined.
  • Under IBM i (for the hfs file system), the default is FILE, which makes end-of-line terminator consistent with file ccsid.

linelen

A positive integer

Maximum length of each line of data (record under the z/OS dd and dsn file systems) written. It applies only to the destination side of a transfer and is used in conjunction with the lineop and padline attributes.
 
Default is 0.

  • Under Windows, UNIX, and the hfs file system, this means no line operation takes place.
  • Under z/OS (for the dd and dsn file systems), the value linelen will be set equal to the logical record size used in allocating the destination file.

lineop

none, stream, wrap, or trunc

Line operation for transferred lines (records under the z/OS dd and dsn file systems).
 
For the line operation to be in play in the transfer, the value of linelen must not be zero (linelen is set automatically for the z/OS dd and dsn file systems to the logical record size if it is zero).

  • If value is none, each source line or record or data is written as it is received as a complete line or record. If the length of the source line is greater than that specified by *linelen*, UDM issues an error and the transfer operation is aborted.
  • If value is stream, the source data is treated as one long, single line of data. The source data is broken into multiple lines (records), each with a length of that specified by linelen.
  • If value is trunc, each source line longer than the value specified by linelen is truncated to be exactly linelen characters long.
  • If value is wrap, each source line longer than the value specified by linelen is broken up into multiple lines, each no longer than linelen characters long. Each segment is written out as a separate line (record).

Note

If an end of line sequence is specified, the length of the sequence is not considered by UDM when determining the length of a line on the destination side. UDM only looks at the raw data that is transferred.

 
(By default, the lineop attribute is not defined.)

mode

Set of three numbers (0-7) or nothing.

Note

This attribute is used only for UDM for UNIX.

 
Specification for the mode (in UNIX parlance), or file permissions, of a file created by UDM in a copy operation. Existing files do not have their modes modified by UDM. They retain the file mode that they had before the copy operation was initiated.
 
Each number in the set corresponds to one or more individuals for whom access is granted for the file:

  • First number: Owner of the file.
  • Second number: Users in the group assigned to the file.
  • Third number: Everyone else.


The value of each number is the sum of values representing file permissions:

  • 0 - No permissions.
  • 1 - Permission to execute the file.
  • 2 - Permission to write to the file.
  • 4 - Permission to read from the file.


 
(By default, the mode attribute is not set. The default mode of a newly created file by UDM is dependent upon the user's umask or the mode of the source file in a UDM transfer.)

ostype

AIX, HP, Linux, Solaris, USS, Windows, or z/OS

Type of operating system. This attribute is associated with UDM server. Its default value is set based on the platform that the UDM component was compiled for.

padline

none, null, or space

Specification for whether or not data is padded. (Used in conjunction with linelen, when linelen is not zero.)

  • If value is none, each line (record) of data written is not padded.
  • If value is null, each line of data is padded with null characters (hex value 0) at the end until the line is linelen characters in length.
  • If value is space, each line of data is padded with spaces at the end until the line is linelencharacters in length.


 
Default is none.

rdw

yes or no

Specifies how to manage files whose records may start with a 4-byte Record Descriptor Word (RDW). This RDW contains the record length for variable-length record data that originates from z/OS, and is structured as follows:

  • Bytes 1 & 2
    Length of the logical record, including the 4-byte RDW.
  • Byte 3
    A segment flag, with the following values:
    • 0 - Complete record contained in a single logical record.
    • 1 - Logical record is split across multiple segments, and this is the first.
    • 2 - Logical record is split across multiple segments, and this is the last.
    • 3 - Logical record is split across multiple segments, and this is a middle record.
  • Byte 4
    Unused


The role that the rdw attribute plays varies depending on context.
 
For files transferred from z/OS:

  • If the value is yes, the 4 bytes of the RDW are stored in the destination file.
  • If the value is no, the RDW is stripped from the record prior to transfer and is not stored in the destination file.


For files transferred to z/OS:

  • If the value is yes, UDM recognizes that the input file contains one or more logical records, and that the first 4 bytes of each those records is an RDW. The length of each logical record is used to deliver separate physical records to the z/OS system. To have the logical records stored as physical records on z/OS, you must set the linelen and lineop attributes. linelen should be the dataset's record length minus 4, and lineop must be wrap (for example, attrb dst linelen=LRECL-4 lineop=wrap, where LRECL is the record length specified in the dataset's DCB info).

    When the records are sent back to z/OS, the RDW is removed from the data. The new records receive an RDW from the OS as the dataset is written.

  • If the value is no, UDM will not apply any special handling to the records and will transfer them as-is.


The default is no.
 

Note

The RDW is stored in binary format. To prevent conversion of the record length to a text value, transfer the file as binary using the mode type=binary command.

regex

yes or no

Allows regular expression pattern matching to select which files are chosen for the copy, delete, dir, and move commands, and the forfiles.
 
If the value of this attribute is yes, file names specified for the corresponding session are processed in a grep-like fashion. Care must be taken when crafting the expression to ensure that only the files desired are processed.
 
For example, given the script commands:
 

open src=somehost user=uid pwd=pwd
attrib src regex=yes

cd src=d:\rootdir\datadir
copy src=^[AaBb]

 
Any files in d:\rootdir\datadir that contain the substring 123.txt - including the file named 123.txt - will be copied.
 
Use regular expression control characters such as ^ and $ to limit the substring to match the beginning and ending of file names. For example, use ^123.txt$ to copy just the file named 123.txt. Additional information on regular expressions, including the different matching patterns that are available, can be found in a number of online resources and UNIX man pages.
 
Also, remember that wildcards are treated as special control characters in regular expressions. Set this attribute to no or omit it entirely to have UDM process wildcard characters as a "true" wildcard.
 
Default is no.
 

Note

Regular expression pattern searches are case-insensitive on Windows systems. For Unix and z/OS sessions, they are case-sensitive.
 
On z/OS, the regex attribute is available only for the HFS and DSN file systems, not the DD (ddname) file system.

srccreatetime

yes or no

Note

This attribute is used only for UDM for Windows.

 
Specification for whether or not the creation timestamp of the destination file in a copy operation matches the creation timestamp of the source file.

  • If value is yes, the creation timestamp of the destination file matches the creation timestamp of the source file.
  • If the value is no, the creation timestamp of the destination file does not match the creation timestamp of the source file.


 
Default is no.

srcmodtime

yes or no

Note

This attribute is used only for UDM for UNIX, Windows, and IBM i.

 
Specification for whether or not the modification timestamp of the destination file in a copy operation matches the modification timestamp of the source file.

  • If value is yes, the modification timestamp of the destination file matches the modification timestamp of the source file.
  • If the value is no, the modification timestamp of the destination file does not match the modification timestamp of the source file.


 
Default is no.

srcaccesstime

yes or no

Note

This attribute is used only for UDM for UNIX, Windows, and IBM i.

 
Specification for whether or not the last access timestamp of the destination file in a copy operation matches the last access timestamp of the source file prior to the copy operation.

  • If value is yes, the last access timestamp of the destination file matches the last access timestamp of the source file prior to the copy operation.
  • If the value is no, the last access timestamp of the destination file does not match the last access timestamp of the source file prior to the copy operation.


 
Default is no.

trans

yes or no

Specification for whether or not a transactional file copy is to be performed:

  • If value is yes, the file is copied to a file with a temporary name (format: udmtmp-yyMMdd-hhmmss-pid-fileno, where pid is the UDM Server process ID and fileno is the nth file in the transfer) that is renamed to the destination filename once the file has been successfully transferred.
  • If value is no, the file is copied directly to the specified destination filename.


 
Default is no.
 

Note

For z/OS and IBM i, trans is valid only under the hfs file system.

truncext

yes or no

Specification for whether or not the source filename's extension should be truncated if it is being used as the destination filename (no filename was explicitly specified on the destination side of the transfer operation).

  • If value is yes, the extension is truncated.
  • If value is no, the filename is left untouched.


 
Default is no.
 

Note

UDM considers a file extension to be the sequence of characters following the last dot (.) character in the filename. When an extension is truncated, the dot marks the beginning of the extension and is truncated as well. UDM will not consider the a dot character as the first character in a filename as indicating a file extension.

umask

Three-digit octal value.

File permissions mask used to create the destination file or directory. When the source file comes from an HFS file system and the source UDM component version is 3.2 or greater, the file permission mode is set based upon the source file permission mode. Directory permission modes are always set based on the UMASK attribute or option.
 

Note

For UNIX and z/OS (under the hfs file system), umask is valid only on the destination side of the transfer.

usefqn

yes or no

Specification, when copying a data set under the dsn file system, whether or not the fully qualified data set name is sent over as the source file name to be used by the destination if an explicit destination filename is not given.

  • If value is yes, the fully qualified data set name is sent.
  • If value is no, only the part of the data set name matching the source mask in the copy operation is used as the destination filename.


 
Default is no.
 

Note

For z/OS, usefqn is valid only on the source side of the transfer.

Example

To set the line length, line operation, and line padding sequence:

attrib ntmachine linelen=80 lineop=wrap padline=none