Splitting a joined file

The files that are joined and then transferred can be split and output into separate files. When the command outputs the files, it divides the files while carrying out code conversion based on the information at the time of joining and the specified parameter.

(1) Joined File Split command

Program interface

CALL library name/UTLBREAK PARM(['LIB=library name'] 'INFILE=filename'
   ['OUTLIB=library'] {{{['SEQNBR=number']|['TGTFILE=filename']}
   ['OUTFILE=filename'] ['RCDSIZE=recordsize']}|
   {['FROM=number'] ['TO=number'] ['RCDSIZE=recordsize']}}
   ['CODESET=0|A|B|C|D|E|F|G|H|I|V|W|X'] ['SHIFT=Y|N|C|S'] ['R'] ['TABCHG=0|1']
   ['B'] ['G'] ['OUTPUT=filename'] ['EXIT' CLvariable name])

Explanation of parameters

LIB=Library name

Library name in which HULFT is installed ("HULFT" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

INFILE=infile

Joined file name (Mandatory)

Specify this parameter in the format of Library name/File name(Member name).

OUTLIB=library

Library name to which a split file is output (Optional)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

SEQNBR=number

Specify this parameter to split the joined file according to the specification of the sequence number in joined file (Optional)

Specify this parameter in the range of "1" to "9999".

If parameter "OUTFILE=" is omitted, the output file is named automatically according to the name of the joined file. For details, refer to (2) Naming convention for the output file .

When you omit "SEQNBR=", specify at least one of the tags among "TGTFILE=", "FROM=", or "TO=".

TGTFILE=filename

Specify this parameter to split the file according to the file name within the joined file (Optional)

If parameter "OUTFILE=" is omitted, the output file is named automatically according to the name of the joined file. For details, refer to (2) Naming convention for the output file .

For specification of parameter "TGTFILE=", specify the file name that will be output when you run the Joined File Display command. For details, refer to Displaying the content of a joined file .

When you omit "TGTFILE=", specify at least one of the tags among "SEQNBR=", "FROM=", or "TO=".

OUTFILE=filename

Name of the split file (Optional)

Specify this parameter in the format of Library name/File name(Member name).

If omitted, the output file is named automatically according to the name of the joined file. For details, refer to (2) Naming convention for the output file .

RCDSIZE=recordsize

Record length of the split file (Optional)

Specify this parameter in the range of "1" to "32766".

You cannot omit this parameter if you split the file with "Binary" specified for the File Type in the File Joining command on HULFT for UNIX or on HULFT for Windows.

FROM=number TO=number

Split the joined file according to the specification of the sequence number range in joined file. (Optional)

Specify this parameter in the range of "1" to "9999".

If you omit "FROM=", all the numbers up to the value that you specified for the "TO=" become the target of this command.

If you omit "TO=", all the numbers higher than the value that you specified for the "FROM=" become the target of this command.

The output file is named automatically according to the name of the joined file. For details, refer to (2) Naming convention for the output file .

When you omit "FROM=", specify at least one of the tags among "SEQNBR=", "TGTFILE=", or "TO=".

When you omit "TO=", specify at least one of the tags among "SEQNBR=", "TGTFILE=", or "FROM=".

RCDSIZE=recordsize

Record length of the split file (Optional)

Specify this parameter in the range of "1" to "32766".

You cannot omit this parameter if you split the file with "Binary" specified for the File Type in the File Joining command on HULFT for UNIX or on HULFT for Windows.

CODESET=0|A|B|C|D|E|F|G|H|I|V|W|X

EBCDIC Set (Optional)

0 :: Autoconfiguration
A :: Katakana
B :: Lowercase
C :: ASCII
D :: ASPEN
E :: Japan (Latin) for IBM
F :: Japan (Latin) Extended for IBM
G :: NEC Katakana
H :: Japan (Katakana) Extended for IBM
I :: Simplified Chinese Extended
V :: User Table 1
W :: User Table 2
X :: User Table 3

If omitted, "0" is set.

SHIFT=Y|N|C|S

Handling of the shift codes at the time of conversion of double-byte codes (Optional)

Y :: Add shift codes
N :: Do not add shift codes
C :: Remove shift codes
S :: Convert shift codes into space codes (ASCII:0x20)

When omitted, HULFT sets the following value for this parameter depending on Code Set for Transfer (CS4TRNSFR) specified in the System Environment Settings:

When Code Set for Transfer (CS4TRNSFR) is set to "IBM Kanji" or "IBM Simplified Chinese" in the System Environment Settings, the parameter is set to "Y".

When Code Set for Transfer (CS4TRNSFR) is set to "UTF-8"in the System Environment Settings, the parameter is set to "C".

R

Replacement of output file at destination (Optional)

If omitted, an error occurs when the file with the same name as the split file already exists.

TABCHG=0|1

Handling of tab codes on conversion from Shift-JIS, EUC-JP, UTF-8, or GB18030 (Optional)

0 :: Convert tab codes into space codes (0x40) of EBCDIC
1 :: No Conversion (tab codes remain as 0x09)

If omitted, "0" is set.

The setting of this field is effective when the combination of code sets is one of the below.

Code Set for Transfer (CS4TRNSFR) of Host That Splits File	Code Set for Transfer of Host That Joined File
IBM Kanji	Shift-JIS, EUC-JP, or UTF-8
IBM Simplified Chinese	GB18030 or UTF-8

When Code Set for Transfer (CS4TRNSFR) is set to "UTF-8" in the System Environment Settings, the setting of this field is not effective.

B

Control of messages at the time of splitting (Optional)

If omitted, HULFT outputs messages each time splitting is completed.

G

Control of error messages that the Joined File Split command outputs (Optional)

When omitted, HULFT displays error messages.

OUTPUT=filename

Destination of the error messages that the Joined File Split command outputs (Optional)

Specify this parameter in the format of Library name/File name(Member name).

When omitted, error messages are not output.

The number of log records that a log file can retain is unlimited.

EXIT CL variable name

Specifies to receive the error code output by the Joined File Split command and specifies the CL variable name to set the error code value (Optional)

The CL variable name must be immediately after the EXIT tag.

HULFT sets an error code to the CL variable only if the command ends unsuccessfully.

When omitted, an error code is not set.

Note

You cannot specify "SEQNBR=", "TGTFILE=" and "FROM=" "TO=" at the same time.
Use "OUTFILE=" in combining with either "SEQNBR=" or "TGTFILE=". When you specify "FROM=" or "TO=", you cannot use "OUTFILE=".
Specify at least one of the tags among "SEQNBR=", "TGTFILE=", "FROM=", or "TO=".
If the value specified by parameter "RCDSIZE=" is small, the command may end with an error due to overflow, depending on data. Specify a value that is large enough.
If you join a file of which name includes double byte codes, you cannot use the name of the original file as a name of an output file on splitting a joined file.

Be sure to specify the output file name (OUTFILE) when splitting the file.

If you omit the value or select "0" (Autoconfiguration) for the parameter "CODESET=", the value for EBCDIC Set used when splitting the file is determined as below.

Table 6.1 Values of EBCDIC Set determined automatically
Code Set for Transfer on the local host	Code Set for Transfer on the remote host
Code Set for Transfer on the local host	UTF-8	SHIFT-JIS	EUC-JP	GB18030	IBM Kanji	JEF	KEIS	NEC Kanji	IBM Simplified Chinese
IBM Kanji	F	F	F		F	F	F	F
UTF-8	-	-	-	-	F	A	D	G	I
IBM Simplified Chinese	I			I					I

-: Combinations of code sets that is not used for the code conversion when splitting a joined file

N: Combinations of code sets that cannot be converted when splitting a joined file

A: Katakana

D: ASPEN

F: Japan (Latin) Extended for IBM

G: NEC Katakana

I: Simplified Chinese Extended

For details on Code Set for Transfer (CS4TRNSFR) in the System Environment Settings by which the code set used when the file is split on the host is specified, refer to Administration Manual.

You can set the code set to be used when the files are joined as Code Set for Transfer (CS4TRNSFR) in the System Environment Settings of the host where the files are joined. For details, refer to Administration Manual of the host where the files are joined.

= Remarks =

You can repeat the specification of "SEQNBR=" or "TGTFILE=" up to 10 times in total.
If parameter "OUTLIB=" is omitted, the library where the joined file is located is used as output destination library. If the parameter "OUTFILE=" is specified, the specification of "OUTFILE=" prevails.

Command interface

UTLBREAK JOINFILE( ) JOINMBR( ) OUTLIB( ) FROMTO((firstnum lastnum recordlen))
   SEQNBR((number file member recordlen)) TGTFILE((targetfile file member recordlen))
   CODESET( ) SHIFT( ) REP( ) TAB( ) BLD( )
   LIBRARY( ) MSG( ) FILE( ) MBR( )

Explanation of parameters

JOINFILE

Library name and file name of the joined file (Optional)

Specify this parameter in the format of Library name/File name.

Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

JOINBR

Member name of the joined file (Mandatory)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

OUTLIB

Library name to which a split file is output (Optional)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

FROMTO

Split the joined file according to the specification of the sequence number range in joined file. (Optional)

When you omit this parameter, specify either "SEQNBR" or "TGTFILE".

firstnum

Sequence number to start

Specify this parameter in the range of "1" to "9999".

lastnum

Sequence number to end

Specify this parameter in the range of "1" to "9999".

recordlen

Record length of split file

Specify this parameter in the range of "1" to "32766".

You cannot omit this parameter if you split the file with "Binary" specified for the File Type in the File Joining command on HULFT for UNIX or on HULFT for Windows.

SEQNBR

Specify this parameter to split the joined file according to the specification of the sequence number in joined file (Optional)

When you omit this parameter, specify either "TGTFILE" or "FROMTO".

number

Sequence number in joined file

Specify this parameter in the range of "1" to "9999".

file

Library name and file name of the split file

Specify this parameter in the format of Library name/File name. Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

member

Member name of the split file ("*FILE" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

recordlen

Record length of split file

Specify this parameter in the range of "1" to "32766". You cannot omit this parameter if you split the file with "Binary" specified for the File Type in the File Joining command on HULFT for UNIX or on HULFT for Windows.

= Remarks =

You can describe the specification of "SEQNBR" and "TGTFILE" 10 times in total at maximum.

TGTFILE

Specify this parameter to split the file according to the file name within the joined file (Optional)

When you omit this parameter, specify either "FROMTO" or "SEQNBR".

targetfile

Library name and file name of the specified file

Specify this parameter in the format of Library name/File name. Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

file

Library name and file name of the split file

Specify this parameter in the format of Library name/File name. Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

member

Member name of the split file ("*FILE" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

recordlen

Record length of split file

= Remarks =

You can describe the specification of "SEQNBR" and "TGTFILE" 10 times in total at maximum.

CODESET

EBCDIC Set (0 by default)

0 :: Autoconfiguration
A :: Katakana
B :: Lowercase
C :: ASCII
D :: ASPEN
E :: Japan (Latin) for IBM
F :: Japan (Latin) Extended for IBM
G :: NEC Katakana
H :: Japan (Katakana) Extended for IBM
I :: Simplified Chinese Extended
V :: User Table 1
W :: User Table 2
X :: User Table 3

SHIFT

Handling of the shift codes at the time of conversion of double-byte codes

(By default, HULFT sets "Y" when the code set is IBM Kanji or IBM Simplified Chinese and sets "C" when the code set is UTF-8, respectively.)

N :: Do not add shift codes
Y :: Add shift codes
C :: Remove shift codes
S :: Convert shift codes into space codes (ASCII:0x20)

REP

Replacement of output file at destination (N by default)

N :: Give an error when the file already exists.
Y :: Replace the existing file with new one when the file already exists.

TAB

Handling of tab codes on conversion from Shift-JIS, EUC-JP, UTF-8, or GB18030 ("0" by default)

0 :: Convert tab codes into space codes (0x40) of EBCDIC
1 :: No Conversion (tab codes remain as 0x09)

The setting of this field is effective when the combination of code sets is one of the below.

Code Set for Transfer (CS4TRNSFR) of Host That Splits File	Code Set for Transfer of Host That Joined File
IBM Kanji	Shift-JIS, EUC-JP, or UTF-8
IBM Simplified Chinese	GB18030 or UTF-8

When Code Set for Transfer (CS4TRNSFR) is set to "UTF-8" in the System Environment Settings, the setting of this field is not effective.

BLD

Control of messages at the time of splitting (Y by default)

N :: Do not output messages.
Y :: Output messages each time splitting is completed.

LIBRARY

Library name in which HULFT is installed ("HULFT" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

MSG

Control of error messages ("*YES" by default)

*NO :: Suppress error messages.
*YES :: Show error messages.

FILE

Name of the library and the file to which error messages are output (Optional)

Specify this parameter in the format of Library name/File name.

Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

When omitted, error messages are not output. The number of log records that a log file can retain is unlimited.

MBR

Member name of the file to which error messages are output ("*FILE" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

(2) Naming convention for the output file

If the output file name is omitted at the time of splitting, files are automatically generated according to the naming conventions below, based on the host type on which the joined file was created.

When the joined file is created by HULFT for UNIX

Input File Name When Joined File Is Created	Output File Name
/TEST1/TEST2/TEST3.TXT	Library name/TXT(TEST3)
../TEST1/TEST2/TEST3	Library name/TEST3(TEST3)

When the joined file is created by HULFT for Windows

Input File Name When Joined File Is Created	Output File Name
C:\TEST1\TEST2\TEST3.TXT	Library name/TXT(TEST3)
..\TEST1\TEST2\TEST3	Library name/TEST3(TEST3)

When the joined file is created by HULFT for IBMi

Input File Name When Joined File Is Created	Output File Name
MYLIB/TXT(TEST)	Library name/TXT(TEST)

When the joined file is created by HULFT for Mainframe

Input File Name When Joined File Is Created	Output File Name
Sequential Organization File: TEST1.TEST2.TEST3.TXT	Library name/TXT(TEST3)
Partitioned Organization File: TEST1.TEST2.TEST3(TXT)	Library name/TEST3(TXT)

Note

The conversion rules mentioned above are applied only when the parts used as file name and member name satisfy the following conditions:

The name consists of only single-byte codes.
The name starts with one of the following; uppercase alphabetic characters (A to Z), number sign (#), at sign (@)
The character that is used for second byte or after is one of the following; uppercase alphabetic characters (A to Z), number sign (#), at sign (@), numbers (0 to 9), underscore (_), period (.)
The maximum length of the name is 10 bytes.

If above mentioned rules are not satisfied, the following conversion rules are used:

The output file uses the name of an input file (namely, the joined file) .
Regarding the member name, use the name of corresponding component that is followed by a 4-digit sequence number. (If the length of corresponding component part exceeds 6 bytes, use the first 6 bytes of the string, which is followed by a 4-digit sequence number.)
Example:
When the name of the input file is "MYLIB/JOIN(TEST)" and the name of the fifth file created on splitting does not conform to the naming convention:
```
Library name/JOIN(TEST0005)
```

(3) Description example

Specification by sequence number

CALL HULFT/UTLBREAK PARM('INFILE=MYLIB/JOIN1(DATA)' 'SEQNBR=1'
   'OUTFILE=MYLIB/BREAK1(DATA1)' 'SEQNBR=3' 'OUTFILE=MYLIB/BREAK1(DATA3)')

CALL HULFT/UTLBREAK PARM('INFILE=MYLIB/JOIN2(DATA)' 'SEQNBR=1' 'SEQNBR=3'
   'OUTLIB=MYLIB')

Specification by file name

CALL HULFT/UTLBREAK PARM('INFILE=MYLIB/JOIN3(DATA)'
   'TGTFILE=TESTLIB/TEST3(MBR3)' 'OUTFILE=MYLIB/BREAK3(DATA3)')

CALL HULFT/UTLBREAK PARM('INFILE=MYLIB/JOIN4(DATA)'
   'TGTFILE=TESTLIB/TEST4(MBR4A)' 'TGTFILE=TESTLIB/TEST4(MBR4B)'
   'OUTLIB=MYLIB' 'R')

Specification by range of sequence numbers

CALL HULFT/UTLBREAK PARM('INFILE=MYLIB/JOIN5(DATA)' 'FROM=1' 'TO=10'
   'OUTLIB=MYLIB' 'R')