CitSORT® Options, Statements and Clauses

Statements

ALTSEQ Statement

The ALTSEQ statement is used to change the alternate translation table (ALTSEQ table). Modifications are applied to the standard ASCII/EBCDIC translation table. When using the ALTSEQ statement, the TRAN=ALTSEQ clause must be used in context (any segment list that can include an EDIT or FORMAT clause may include a TRAN=ALTSEQ clause) to apply the modifications described by the ALTSEQ statement.

General Format:

[ALTSEQ CODE=({old char1, new char1}...)]

ALTSEQ Statement used to modify data in copy of existing file:

       >CITSORT FIELDS=COPY USE PRESIDENTS.DAT RECORD F 85 GIVE TESTOUT.DAT
       ALTSEQ CODE=(0540,0E40)
       OUTREC FIELDS=(1,4,5,TRAN=ALTSEQ)

ALTSEQ Statement used with an INREC:

       >CITSORT FIELDS=(1,80,CH,A),SKIPREC=1
       USE PRESIDENTS.DAT RECORD F85 GIVE TESTOUT.DAT
       INCLUDE COND=(1,80,CH,NE,C'        ')
       ALTSEQ CODE=(7F40,6D60)
       INREC FIELDS=(1,80,TRAN=ALTSEQ)
       SUM    FIELDS=NONE
       OUTREC FIELDS=(2,64,16X)

ALTSEQ Statement used with an OUTREC:

       >CITSORT FIELDS=COPY
       USE PRESIDENTS.DAT RECORD F85 GIVE TESTOUT.DAT
       ALTSEQ CODE=(0040,0140,0240,0340,0440,0540,0640,0740,0840,0940)
       OUTREC FIELDS=(1,80,TRAN=ALTSEQ)

ALTSEQ Statement used with a single value:

       >CITSORT FIELDS=(1,80,CH,A),SKIPREC=1
       USE PRESIDENTS.DAT RECORD F85 GIVE TESTOUT.DAT
       INCLUDE COND=(1,80,CH,NE,C'        ')
       ALTSEQ CODE=(7F40)
       INREC FIELDS=(1,80,TRAN=ALTSEQ)
       SUM    FIELDS=NONE
       OUTREC FIELDS=(2,64,16X)

USE Statement

The USE Statement declares the input files, as well as record type, and record length, and the overall organization of the file, whether it is a Sequential, Line Sequential, or Relative file.

General Format:

       USE input-file 
       RECORD [record definition] 
       [ORG   file organization] 
       [KEY ({start-pos,length,type}...)]

RECORD Clause (USE Statement)

The RECORD Clause of the USE Statement describes the record format fixed-length, or variable-length and record-length of the input file.

General Format:

RECORD record-type, length, [max-length]

Syntax:

Record-type is either F (fixed-length) or V (variable-length).

General Rules:

If the RECORD format is variable length, the length parameter holds min-length.

For variable length files, both min-length and max-length are required.
The RECORD Clause is required.

ORG Clause (USE Statement)

The ORG Clause of the USE Statement describes the organization-relative, indexed, sequential, or line-sequential of the output file.

General Format:

[ORG org-type]

Syntax:

Org-type is one of the following:

Type	Description
`RL`	organization is relative
`IX`	organization is indexed (Require a `KEY` clause)
`IX1`	organization is indexed, and compressed*
`SQ`	organization is sequential
`LS`	organization is line sequential (Linux/Unix record terminators of `LF`)
`LSD`	organization is line sequential (DOS record terminators of `CR`/`LF`)**

*When data is compressed in an indexed file, you must describe the organization as ix1, you must declare all indexes.

As an example:

       citsort copy
              use DATAFIL
                     org ix1 key=(1,18, P, 291,10, AD) record f
              1100 give DATAFILsort
              org sq record f 1100

**The environment variable CITSORT_LS_DOS forces record terminators for all line sequential files to be CR/LF. For existing installations, where CitSORT is being used in a DOS environment, and where scripts use an org ls notation, this would be required when updating to version 3.4.18 or later, as the behavior of CITSORT has changed, and by default, the org ls notation causes record terminators of LF to be created.

General Rules:

The ORG clause is optional.
The default value of org-type is sequential (SQ).

Examples:

USE Statement, Fixed-Length RECORD clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

USE Statement, Variable-Length RECORD clause

       >CITSORT USE PRESIDENTS2.TXT RECORD V 12 24 ORG LS SORT FIELDS (1,2,NU,A) 
       GIVE PRES3.TXT ORG LS

USE Statement, ORGANIZATION Sequential File

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 ORG SQ SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

USE Statement, ORGANIZATION Line Sequential (DOS) File

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 ORG LSD SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LSD

USE Statement, ORGANIZATION Relative File

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 ORG RL SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

USE Statement, No ORGANIZATION Clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

KEY Clause (USE Statement)

The KEY Clause of the USE Statement describes the keys of indexed files.

General Format:

KEY ({start-pos,length,type}...)]

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes.

Type is one of the following:

Syntax	Description
P	Primary key
A	Alternate key
AD	Alternate key with duplicates
C	Component of the last-specified primary or alternate key.

General Rules:

The KEY clause is required for Indexed files.
Primary key must be the first describer key.
Primary key may not have duplicates.
You must define the keys in order of importance, the primary key first, followed by all its components if it is split, then the first alternate key and all of its components, and so on.

Examples:

Copy the data from PRESIDENT_IX into LINE SEQUENTIAL file PRES2.TXT

       >CITSORT COPY USE PRESIDENTS_IX RECORD F 85 ORG IX KEY (1,2,P,3,5,AD,10,5,C) 
       GIVE PRES2.TXT ORG LS

PRESIDENT_IX is INDEXED has record of 85 byte and keys are:

Primary: From byte 1 for 2 Byte.
Alternate: Split key with duplicates, First part from 3 for 5 byte and second part from
10 for 5 bytes.

FIELDS Statement

The FIELDS Statement describes the SORT keys to be used for an input file. SORT keys are described in the FIELDS statement, by their starting position, length, data-type, and sort-order. Multiple SORT keys can be described for a single SORT operation.

General Format:

FIELDS ({start-pos,length,[data-type], sort-order}...) [format=data-type] [TRAN=ALTSEQ])

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1. Length is the length of the field in bytes
Data-type is a 2-byte abbreviation for a COBOL data type.

General Rules:

The 2-byte data-types and corresponding COBOL data types are listed in the data-type table below.

Data-type Abbreviation	COBOL data type
CH	PIC X USAGE DISPLAY
NU	PIC 9 USAGE DISPLAY
PD	PIC S9 COMP-3
FI	PIC S9.99 USAGE DISPLAY
BI	USAGE COMP
C5	USAGE COMP-5
S5	PIC S9 USAGE COMP-5
CX	USAGE COMP-X
LS	PIC S9 LEADING SEPARATE
LI	PIC S9 LEADING INCLUDED
ZD	PIC 9 USAGE DISPLAY
FS	PIC S9.99 USAGE DISPLAY

Sort-order is either A (ascending) or D (descending).
When the FORMAT clause is used to describe the data-type, the data-type is not included in the FIELDS Clause.

FORMAT Clause

The FORMAT Clause describes the data type of the FIELDS in a SORT Statement.

General Format:

[FORMAT=data-type]

Syntax:

Data-type is a 2-byte abbreviation for a COBOL data type.

General Rules:

When used, the FORMAT Clause replaces the data-type entry in the FIELDS Clause.
The FORMAT Clause is set to a data-type abbreviation (see data type table above).
Format may be used when sorting on a single key, but is more useful when sorting on multiple keys that have the same data type.

SKIPREC Clause

The SKIPREC Clause indicates the number of records to skip before beginning to process the SORT.

General Format:

[SKIPREC=<number>]

Syntax:

<number> is an integer describing the number of records to skip before beginning to process the SORT.

General Rules:

When SKIPREC=<number> is indicated, the SORT begins process at record <number> +1.

Examples:

SORT Fields, Sort on Descending, Ascending Order

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,A) 
       GIVE PRES2.TXT ORG LS

SORT Fields, Usage of the Format Clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,A) FORMAT=NU 
       GIVE PRES2.TXT ORG LS

SORT Fields, Usage of the SKIPREC Clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,A) FORMAT=NU SKIPREC=1 
       GIVE PRES2.TXT ORG LS

SORT Fields, Sort on Multiple Keys

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (43,21,CH.A,1,2,CH,A) 
       GIVE PRES2.TXT ORG LS

SORT Fields, Usage of the Format Clause on Multiple Key Sort

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (43,21,A,3,22,A) FORMAT=CH
       GIVE PRES2.TXT ORG LS

INREC Statement

INREC provides a mechanism for taking portions of an input file, and creating a new input file for the SORT function. There could be a number of possible reasons for doing this, however performance is probably the most likely. If an input file is very long, it can be reduced in length, by selecting a subset of its fields, formatting them in a shorter file, and achieving better performance on the SORT. Subsequent SORT FIELDS and SUM FIELDS statements must refer to the offsets created by the INREC FIELDS statement, not to the offsets in the original input file.

INREC also provides an IFTHEN clause which allows you to reformat lines before sorting them according to characteristics detected in your IFTHEN condition.

General Format:

       [INREC {FIELDS[=] {start-pos,length,}...)]
              [IFTHEN= (WHEN= (start-pos,length,data-type,comparison-expression), 
                     BUILD= ([{format-char}]...) 
                            {start-pos, length,{data-format1}]

The IFTHEN clause, with WHEN and BUILD subclauses are supported in the INREC and OUTREC statements.

As an example:

Consider a case where a line sequential file contains a header and trailer record that have different formats than the main body of the sequential file, for example:

       hdr 14-jun-2018
       04James Madison      180903041817030408Democratic-Republican   George Clinton
       03Thomas Jefferson   180103041809030408Democratic-Republican   Aaron Burr
       02John Adams         179703041801030404Federalist              Thomas Jefferson
       01George Washington  178904301797030408Independent             John Adams
       trl    4 records total

The following CITSORT could be used to sort the body of this file, while leaving the header and trailer files in place:

       USE PRES2.TXT RECORD F 85 ORG LS
       INREC IFTHEN=(WHEN=(1,3,CH,EQ,C'hdr'), BUILD=(C'00',1,25)),
       IFTHEN=(WHEN=(1,3,CH,EQ,C'trl'), BUILD=(C'05',1,25)),
       IFTHEN=(WHEN=(1,2,NU,GE,00), BUILD=(1,85))
       SORT FIELDS=(1,2,NU,A)
       GIVE PRES3.TXT RECORD F 85 ORG LS
       OUTREC IFTHEN=(WHEN=(1,2,CH,EQ,C'00'),BUILD=(3,23)),
       IFTHEN=(WHEN=(1,2,CH,EQ,C'05'), BUILD=(3,23))

The first INREC/IFTHEN statement creates a condition when character 1-3 are "hdr". In this case, the the characters "00" are inserted at the beginning of the line followed by the characters 1 thru 25 of the line.

The second INREC/IFTHEN statement creates a condition when character 1-3 are "trl". In this case, the characters "05" are inserted at the beginning of the line followed by the characters 1 thru 25 of the line.

The third INREC/IFTHEN statement creates a condition for the modified body of data. The header file has been marked as record "00". The trailer file as record "05". The third INREC/IFTHEN condition applies to all lines, identifed with the first two bytes being numeric and GE 0. The lines are re-written as-is.

The file, originally in descending format, is SORT'ed in ascending format on the numeric fields in bytes 1-2.

The OUTREC/IFTHEN statement strips out the values that have been inserted in character positions 1-2. In records where the first two bytes are "00" or "05", the record is re-built from position 3.

FIELDS Clause (INREC Statement)

The FIELDS Clause of the INREC Statement iterates the starting position, and length in the input file of the data that will be included in the file input to the sort.

General Format:

FIELDS[=] ({start-pos,length,}...[TRANS=ALTSEQ])

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1. Length is the length of the field in bytes

General Rules:

Multiple iterations of Start-pos, length are permitted.
The data offsets created by the INREC operation must be used by subsequent SORT, and SUM operations that identify input data by offset.
TRAN=ALTSEQ activates the code modifications described in the ALTSEQ statement.

Examples:

INREC Statement, Reduce the size of the input record to 40 bytes

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (1,40) SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

SUM Statement

The SUM Statement SUM's the indicated fields, and reports the SUM's for all the fields described, accumulated on the records in the input file that have the same value in the SORT key.

General Format:

[SUM FIELDS ({start-pos,length,data-type}...)]

FIELDS Clause (SUM Statement)

The FIELDS Clause of the SUM Statement iterates the starting position, length, and data-types of the fields that are the target of the SUM.

General Format:

FIELDS ({start-pos,length,data-type}...[TRAN=ALTSEQ])

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes.
Data-type is a 2-byte abbreviation for a COBOL data type.

General Rules:

TRAN=ALTSEQ activates the code modifications described in the ALTSEQ statement.
The 2-byte data-types and corresponding COBOL data types are listed in the data-type table below.

Data-type Abbreviation	COBOL data type
CH	PIC X USAGE DISPLAY
NU	PIC 9 USAGE DISPLAY
PD	PIC S9 COMP-3
FI	PIC S9.99 USAGE DISPLAY
BI	USAGE COMP
C5	USAGE COMP-5
S5	PIC S9 USAGE COMP-5
CX	USAGE COMP-X
LS	PIC S9 LEADING SEPARATE
LI	PIC S9 LEADING INCLUDED
ZD	PIC 9 USAGE DISPLAY
FS	PIC S9.99 USAGE DISPLAY

Only numeric data types may be named in the FIELDS Clause of a SUM Statement.
The SUM statement eliminates records with duplicate sort keys from the output file.
The fields preserved in the output record are taken from the first record in which the sort key is found.
When an INREC Statement has been used, the offsets used in the SUM FIELDS clause must refer to the offsets of file described by the INREC Clause, not the original input file.
When an INREC Statement is used, the SUM Statement must be placed after the INREC Statement.
When SUM Fields is set to (None), the effect is to eliminate all records that have duplicate Sort Keys from the output file, preserving only the first instance.
The SUM Statement may be placed before or after the GIVE statement.

Examples:

SUM, Summing on a numeric fieldmeric field

This report will list all of the political parties, and the total number of years that Presidents from each of the Parties have served.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (43,21,41,2) 
       SORT FIELDS (1,21,CH,A) SUM FIELDS=(22,2,NU) 
       GIVE PRES2.TXT ORG LS

SUM, Eliminating records with a duplicate sort key

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (3,21,CH,A) 
       GIVE PRES2.TXT ORG LS SUM FIELDS=(NONE)

INCLUDE Statement

The INCLUDE Statement describes a sort filter with a portion of the input file, and a comparison expression. If the portion of the file tests true for the comparison, the record is included in the output file.

General Format:

[INCLUDE COND ({start-pos,length,data-type,comparison-expression}...)]

COND Clause (INCLUDE Statement)

The COND Clause defines the condition that is applied to determine if the record is included in the output file.

General Format:

COND ({start-pos,length,data-type,comparison-expression}...)

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes.
Data-type is a 2-byte abbreviation for a COBOL data type.

General Rules:

The 2-byte data-types supported for comparison and corresponding COBOL data types are listed in the data-type table below.

Data-type Abbreviation	COBOL data type
CH	PIC X USAGE DISPLAY
NU	PIC 9 USAGE DISPLAY
PD	PIC S9 COMP-3
FI	PIC S9.99 USAGE DISPLAY
BI	USAGE COMP
C5	USAGE COMP-5
S5	PIC S9 USAGE COMP-5
CX	USAGE COMP-X
LS	PIC S9 LEADING SEPARATE
LI	PIC S9 LEADING INCLUDED
ZD	PIC 9 USAGE DISPLAY
FS	PIC S9.99 USAGE DISPLAY

Comparison-expression is minimally made up of a comparison-operator, and comparison-operand.
Multiple comparison-operator/comparison-operand pairs may be grouped together with the logical-operators AND and OR, as described below.
Comparison-operator is one of the following:

Abbreviation	Description
EQ	Equal to
NE	Not Equal to
GT	Greater Than
GE	Greater Than or Equal
LT	Less Than
LE	Less Than or Equal

Comparison-operand is data being examined.
Character data must be marked with single-quotes.
Logical-operators AND, OR, are supported.
AND statements are evaluated before OR statements.
In comparison expressions, numeric types may be compared against each other or against a constant.
Strings may be compared against each other, a string, or a hexadecimal constant.
Substrings may be included in sort filters, but may only be used with the comparison operators “EQ” (Equal) and “NE” (Not Equal).
Data types BI, C5, C6, CX, LI, LS, NU, PD, S5, SB and ZD may be compared against each other, or against a hexadecimal or decimal constant.
BI and CH may be compared against each other or a string constant.
CH may be compared against a hexadecimal constant.

Examples:

INCLUDE Statement, Character comparison

This example shows the application of a character sort filter, which will only retrieve Presidents, whose first names begin with “John”.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(3,4,CH,EQ,'JOHN')
       GIVE PRES2.TXT ORG LS

INCLUDE Statement, Numeric comparison

This example shows the application of a numeric sort filter, which will only retrieve President number 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (1,40) SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(1,2,NU,EQ,10)
       GIVE PRES2.TXT ORG LS

INCLUDE Statement, Data expressed as hexadecimal

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (1,40) SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(1,2,NU,EQ,X’3130’)
       GIVE PRES2.TXT ORG LS

INCLUDE Statement, Use of Logical AND operator

This example contains a logical AND operator. It will retrieve a list of Presidents numbers greater than 1 and less than 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(1,2,NU,GT,01,AND,1,2,NU,LT,10) 
       GIVE PRES2.TXT ORG LS

INCLUDE Statement, Use of Logical OR operator

This example contains a logical OR operator. It will retrieve a list of Presidents numbers equal 1 or equal 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(1,2,NU,EQ,01,OR,1,2,NU,EQ,10)
       GIVE PRES2.TXT ORG LS

INCLUDE Statement, Use of Substring operator

This example includes records in which the substring ‘John’ has been found inside a 21-byte span of characters in the record.

Note

The substring function can only be used with the “eq” (equal) and “ne” (not equal) comparison operators.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       INCLUDE COND=(3,21,SS,EQ,'JOHN')
       GIVE PRES2.TXT ORG LS

OMIT Statement

The OMIT Statement describes a sort filter with a portion of the input file, and a comparison expression. If the portion of the file tests true for the comparison, the record is omitted from the output file.

General Format:

[OMIT COND ({start-pos,length,data-type,comparison-expression}...)]

COND Clause (OMIT Statement)

The COND Clause defines the condition that is applied to determine if the record is omitted from the output file.

General Format:

COND ({start-pos,length,data-type,comparison-expression}...)

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes
Data-type is a 2-byte abbreviation for a COBOL data type.

General Rules:

The 2-byte data-types supported for comparison and corresponding COBOL data types are listed in the data-type table below.

Data-type Abbreviation	COBOL data type
CH	PIC X USAGE DISPLAY
NU	PIC 9 USAGE DISPLAY
PD	PIC S9 COMP-3
FI	PIC S9.99 USAGE DISPLAY
BI	USAGE COMP
C5	USAGE COMP-5
S5	PIC S9 USAGE COMP-5
CX	USAGE COMP-X
LS	PIC S9 LEADING SEPARATE
LI	PIC S9 LEADING INCLUDED
ZD	PIC 9 USAGE DISPLAY
FS	PIC S9.99 USAGE DISPLAY

Comparison-expression is minimally made up of a comparison-operator, and comparison-operand.
Multiple comparison-operator/comparison-operand pairs may be grouped together with the logical-operators AND, and OR, as described below.
Comparison-operator is one of the following:

Abbreviation	Description
EQ	Equal to
NE	Not Equal to
GT	Greater Than
GE	Greater Than or Equal
LT	Less Than
LE	Less Than or Equal

Comparison-operand is data being examined.
Character data must be marked with single-quotes.
Logical-operators AND, OR, are supported.
AND statements are evaluated before OR statements.
In comparison expressions, numeric types may be compared against each other or against a constant.
Strings may be compared against each other, a string, or a hexadecimal constant.
Substrings may be included in sort filters, but may only be used with the comparison operators “EQ” (Equal) and “NE” (Not Equal).
Data types BI, C5, C6, CX, LI, LS, NU, PD, S5, SB, and ZD may be compared against each other, or against a hexadecimal or decimal constant.
BI and CH may be compared against each other or a string constant.
CH may be compared against a hexadecimal constant.

Examples:

OMIT Statement, Character Comparison

This example shows the application of a character sort filter, which will omit Presidents, whose first names begin with “John”.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       OMIT COND=(3,4,CH,EQ,'JOHN')
       GIVE PRES2.TXT ORG LS

OMIT Statement, Numeric Comparison

This example shows the application of a numeric sort filter, which will only omit President number 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (1,40) SORT FIELDS (1,2,NU,D) 
       OMIT COND=(1,2,NU,EQ,10)
       GIVE PRES2.TXT ORG LS

OMIT Statement, Data expressed as hexadecimal

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 INREC FIELDS (1,40) SORT FIELDS (1,2,NU,D) 
       OMIT COND=(1,2,NU,EQ,X’3130’)
       GIVE PRES2.TXT ORG LS

OMIT Statement, Usage of Logical AND operator

This example shows the application of a numeric sort filter that contains a logical AND operator. It will omit Presidents with numbers greater than 1 and less than 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       OMIT COND=(1,2,NU,GT,01,AND,1,2,NU,LT,10)
       GIVE PRES2.TXT ORG LS

Omit Statement, Usage of Logical OR operator

This example shows the application of a numeric sort filter that contains a logical OR operator. It will retrieve a list of Presidents omitting numbers equal 1 or equal 10.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       OMIT COND=(1,2,NU,EQ,01,OR,1,2,NU,EQ,10) 
       GIVE PRES2.TXT ORG LS

OMIT Statement, Use of Substring operator

This example omits records in which the substring ‘John’ has been found inside a 21-byte span of characters in the record.

Note

The substring function can only be used with the “eq” (equal) and “ne” (not equal) comparison operators.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       OMIT COND=(3,21,SS,EQ,’JOHN’)
       GIVE PRES2.TXT ORG LS

ERROR Statement

The ERROR Statement declares the output files that will be written with record that could not be written in GIVE output file because of Invalid or Duplicated key.

Formal syntax is the same as GIVE statement. See GIVE Statement for syntax detail.

General Format:

       [ERROR error-file  
       RECORD record-type, [min-length],max-length  
              [KEY ({start-pos,length,type}...)]  
       [ORG file-organization]
       [OUTREC [FIELDS] [=] ([{format-char}]...) 
       {start-pos, length,{data-format1} [TO={data-format2}]  

       [change-nomatch conditions]...}]]

General Rules:

To avoid cyclic duplicate key error, use only SQ, RL or LS organization for error files.

GIVE Statement

The GIVE Statement declares the output files, as well as record type, and record length, and the overall organization of the file, whether it is a Sequential, Line Sequential, or Relative file.

General Format:

       GIVE output-file 
       RECORD [record definition] 
       [ORG file organization ] 
       [KEY ({start-pos,length,type}...)]
       [FILLBYTE int <0-255> ]

RECORD Clause (GIVE Statement)

The RECORD Clause of the GIVE Statement describes the record format fixed-length, or variable-length and record-length of the output file.

General Format:

RECORD record-type, length, [max-length]

Syntax:

Record-type is either F (fixed-length) or V (variable-length).

General Rules:

If the RECORD format is variable length, both length and max-length are required.
The RECORD Clause is optional, and if not included, will be the same as the USE file.

ORG Clause (GIVE Statement)

The ORG Clause of the GIVE Statement describes the organization- relative, indexed, sequential, or line-sequential of the output file. The ORG clause is optional. The default is sequential.

General Format:

[ORG org-type]

Syntax:

Org-type is one of the following:

Abbreviation	Description
RL	organization is relative
IX	organization is indexed (Require a KEY clause) IX1 organization is indexed, and compressed*
SQ	organization is sequential
LS	organization is line sequential (Linux/Unix record terminators of LF) LSD organization is line sequential (DOS record terminators of CR/LF)**

*When data is compressed in an indexed file, you must describe the organization as ix1, and you must declare all indexes.

As an example:

       citsort copy
              use DATAFIL
                     org ix1 key=(1,18, P, 291,10, AD) record f 
              1100 give DATAFILsort
              org sq record f 1100

**The environment variable CITSORT_LS_DOS forces record terminators for all line sequential files to be CR/LF. For existing installations, where CitSORT is being used in a DOS environment, and where scripts use an org ls notation, this would be required when updating to version 3.4.18 or later, as the behavior of CITSORT has changed, and by default, the org ls notation causes record terminators of LF to be created.

General Rules:

The default value of org-type is SQ.
When using IX (Index files) Record that generate duplicate key or Invalid key error will be written in the ERROR file if defined.

Examples:

GIVE Statement, Fixed-Length RECORD clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT RECORD F 85 ORG LS

GIVE Statement, Organization Line Sequential

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS

KEY Clause (GIVE Statement)

The KEY Clause of the GIVE Statement describes the keys of indexed files.

General Format:

KEY ({start-pos,length,type}...)]

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes.
type is one of the following:

Abbreviation	Description
P	Primary key
A	Alternate key
AD	Alternate key with duplicates
C	Component of the last-specified primary or alternate key.

General Rules:

The KEY clause is required for Indexed files.
Primary key must be the first describer key.
Primary key may not have duplicates.
You must define the keys in order of importance, the primary key first, followed by all its components if it is split, then the first alternate key and all of its components, and so on.

Examples:

       >CITSORT COPY USE PRESIDENTS_IX RECORD F 85 ORG IX KEY (1,2,P,3,5,AD,10,5,C) 
       GIVE PRES2.TXT ORG LS

Copy the data of the file PRESIDENT_IX into the LINE SEQUENTIAL file PRES2.TXT. PRESIDENT_IX is INDEXED has record of 85 byte and keys are:

Primary: From byte 1 for 2 Byte
Alternate: Split key with duplicates, First part from 3 for 5 byte and second part from
10 for 5 bytes

FILLBYTE Clause (GIVE Statement)

The FILLBYTE Clause of the GIVE Statement describes the character used to pad trailing spaces in a sequential file.

General Format:

FILLBYTE (INT 0-255)

Syntax:

INT is the ASCII value of the FILLBYTE character.

General Rules:

When FILLBYTE is specified, the output record will be padded (if needed) with that byte value instead of space.

Examples:

       > CITSORT COPY USE PRESIDENTS2.TXT ORG LS RECORD V 12,24 
       GIVE PRESIDENTS3.TXT ORG SQ RECORD F 85 FILLBYTE 42

OUTFIL Statements

If you wish to produce more than one output file, with different output and different formats, you can associate an OUTFIL statement with a give statement, and then describe the reformatting associated with the OUTREC statement. You can repeat this process multiple times to produce multiple output files, each of which is formatted differently.

General Format:

       [OUTFIL] 
       [ STARTREC record-number1 ]
       [ ENDREC record-number2 ]
       [OUTREC [FIELDS] [=] ([{format-char}]...)
       {start-pos, length, {data-format1} [TO={data-format2}]
       [change-nomatch conditions]...}]

STARTREC Clause

After a fixed length file has been sorted, the OUTFIL STARTREC clause can be used to indicate that the output file should begin at an offset in the record that is determined by record-number-1. Record-number-1 is the first record that is printed in the output file.

General Format:

[ STARTREC record-number-1 ]

Syntax:

Record-number-1 is a numeric data item or literal.

General Rules:

Record-number-1 is the first record that is printed in the output file.
The STARTREC Clause must be placed after an OUTFIL Clause.

ENDREC Clause

After a fixed length file has been sorted, the OUTFIL ENDREC Clause can be used to indicate that the output file should end at an offset in the record that is determined by record-number-2.

General Format:

[ ENDREC record-number-2 ]

Syntax:

Record-number-2 is a numeric data item or literal.

General Rules:

Record-number-2 is the last record that is printed in the output file.
The ENDREC Clause must be placed after an OUTFIL Clause.

Examples:

OUTFIL, Usage of the STARTREC Clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,D) FORMAT=NU 
       GIVE PRES2.TXT ORG LS OUTFIL STARTREC 40

OUTFIL, Usage of the ENDREC Clause

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,D) FORMAT=NU 
       GIVE PRES2.TXT ORG LS OUTFIL ENDREC 10

OUTFIL, Multiple output files, Multiple OUTRECs

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE OUT1.TXT OUTFIL OUTREC=(1,2,' ',3,22,' ',43,21) 
       GIVE OUT2.TXT ORG LS OUTFIL OUTREC=(3,21,' ',25,4,'-',33,4)

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE OUT1.TXT ORG LS OUTFIL STARTREC=40 OUTREC=1,2,’ ‘,3,22,’ ‘, 43,21) 
       GIVE OUT2.TXT ORG LS OUTFIL ENDREC=5 OUTREC=(3,21,’ ‘, 25,4,’-‘,33,4)

OUTREC Statement

OUTREC provides a mechanism for reformatting an output file, using portions of the output file that have been created by the SORT. This functionality can be useful, as it allows the user to select which fields they would like to see in the output file, and in what order they would like to see them.

OUTREC also provides an IFTHEN clause which allows you to reformat lines based on conditions detected in your IFTHEN condition.

General Format:

       [OUTREC [FIELDS] [=] ([[{format-char}]...)
       {start-pos, length,{data-format} [TO=data-format2]}
       [change-nomatch conditions]...)]]
       [FILLBYTE int <0-255> ]
       [IFTHEN= (WHEN=(start-pos,length,data-type,comparison-expression),
       BUILD=([{format-char}]...){start-pos, length, {data-format 1 } }

The IFTHEN clause, with WHEN and BUILD subclauses are supported in the INREC and OUTREC statements.

As an example:

Consider a case where a line sequential file contains a header and trailer record that have different formats than the main body of the sequential file, for example:

       hdr 14-jun-2018
       04James Madison      180903041817030408Democratic-Republican   George Clinton
       03Thomas Jefferson   180103041809030408Democratic-Republican   Aaron Burr
       02John Adams         179703041801030404Federalist              Thomas Jefferson
       01George Washington  178904301797030408Independent             John Adams
       trl    4 records total

The following CITSORT could be used to sort the body of this file, while leaving the header and trailer files in place:

       USE PRES2.TXT RECORD F 85 ORG LS
       INREC IFTHEN=(WHEN=(1,3,CH,EQ,C'hdr'), BUILD=(C'00',1,25)),
       IFTHEN=(WHEN=(1,3,CH,EQ,C'trl'), BUILD=(C'05',1,25)),
       IFTHEN=(WHEN=(1,2,NU,GE,00), BUILD=(1,85))
       SORT FIELDS=(1,2,NU,A)
       GIVE PRES3.TXT RECORD F 85 ORG LS
       OUTREC IFTHEN=(WHEN=(1,2,CH,EQ,C'00'),BUILD=(3,23)),
       IFTHEN=(WHEN=(1,2,CH,EQ,C'05'), BUILD=(3,23))

The first INREC/IFTHEN statement creates a condition when character 1-3 are "hdr". In this case, the the characters "00" are inserted at the beginning of the line followed by the characters 1 thru 25 of the line.

The second INREC/IFTHEN statement creates a condition when character 1-3 are "trl". In this case, the characters "05" are inserted at the beginning of the line followed by the characters 1 thru 25 of the line.

The third INREC/IFTHEN statement creates a condition for the modified body of data. The header file has been marked as record "00". The trailer file as record "05". The third INREC/IFTHEN condition applies to all lines, identifed with the first two bytes being numeric and GE 0. The lines are re-written as-is.

The file, originally in descending format, is SORT'ed in ascending format on the numeric fields in bytes 1-2.

The OUTREC/IFTHEN statement strips out the values that have been inserted in character positions 1-2. In records where the first two bytes are "00" or "05", the record is re-built from position 3.

FIELDS Clause (OUTREC Statement)

The FIELDS Clause of the OUTREC Statement describes the format of the output file. Formatting capabilities include the ability to add character, change the order of fields, and replace all instances of a given character string with another character string.

General Format:

       [FIELDS] [=] ([{format-char}]...) 
       {start-pos, length, {data-format1}[TO={data-format2}]
       [change-nomatch conditions]...}[TRAN=ALTSEQ]]

Syntax:

Format-char is a character string surrounded by single quotes.
Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes.
Data-format1 is a data format supported by the FIELD statement.
Data-format2 is a data format supported by the FIELD statement.

General Rules

TRAN=ALTSEQ activates the code modifications described in the ALTSEQ statement.
Multiple iterations of Start-pos, length are permitted.
TO= causes a data conversion to be performed on the output file from data-format1 to data-format2.
Change-nomatch conditions can be entered after an iteration of start-pos, length, to scan those bytes for certain values and change them to other values.

CHANGE Clause

The CHANGE Clause describes a scan-string, and a replacement string.

General Format:

[ CHANGE= ({change-length, scan-string, change-string}...) ]

Syntax:

Change-length is the number of bytes that are needed to accommodate the change. Scan-string is the byte, or bytes which are changed when found in the string.

Change-string is the string that will be used to replace scan-string in the output record.

General Rules:

Change-length must be long enough to accommodate the change-string.
The substrings (or characters if the substring has a length of one byte) used in a the scan-string and change-string clauses must be delineated by single quotation marks.

NOMATCH Clause

The NOMATCH Clause stipulates that if a Change condition is not encountered, the bytes identified by the starting-position and length should be preserved in the output file.

General Format:

[ NOMATCH=(start-pos, length ) ]

Syntax:

Start-pos is the offset of the beginning of the field, having marked the first byte as offset 1.
Length is the length of the field in bytes

General Rules:

Bytes identified in tihe NOMATCH Clause will not be changed if they do not match the corresponding CHANGE condition.
If there is no NOMATCH Clause, bytes that do not match the corresponding CHANGE condition are initialized to spaces.

Examples:

OUTREC Statement, Reformatting an output record

This example shows how an OUTREC statement can be used to insert formatting characters into an output file using single quotes, as well as how the output file can be reformatted using the starting-position, length indicators.

       > CITSORT USE PRESIDENTS.DAT ORG SQ RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES3.TXT ORG LS OUTREC FIELDS=('PRESIDENT # ',1,2,' ',3,21)

OUTREC Statement, Reformatting output record, converting data with TO=

This sample illustrates syntax for converting a numeric data item to FS data format using the TO= clause.

       > CITSORT USE PRESIDENTS.DAT ORG SQ RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES3.TXT ORG LS OUTREC FIELDS=(1,2,NU,TO=FS,' ',3,21)

OUTFILE, OUTREC using CHANGE/NOMATCH

This sample changes 1 byte, at position 3 from ‘B’ to ‘W’. Otherwise, the existing data is preserved.

       >CITSORT USE PRESIDENTS.DAT RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES2.TXT ORG LS OUTFIL OUTREC=(1,2,3,1,CHANGE=(1,'B','W',NOMATCH=(3,1)),4,36)

FILLBYTE Clause (OUTREC Statement)

The FILLBYTE Clause of the OUTREC Statement describes the character used to pad trailing spaces in a sequential file.

General Format:

FILLBYTE (INT 0-255)

Syntax:

INT is the ASCII value of the FILLBYTE character.

General Rules:

When FILLBYTE is specified, the output record will be padded (if needed) with that byte value instead of space.

Examples:

       > CITSORT USE PRESIDENTS.DAT ORG SQ RECORD F 85 SORT FIELDS (1,2,NU,D) 
       GIVE PRES3.TXT ORG LS OUTREC FIELDS=('PRESIDENT # ',1,2,' ',3,21), FILLBYTE 42

SORT-EBCDIC functionality

The SORT-EBCDIC function causes record-sequential ASCII files to be sorted in EBCDIC order.

General Format:

       SORT-EBCDIC
       FIELDS ({start-pos,length,[data-type], sort-order}...)
       USE input-file-1 RECORD [record definition] ORG [file organization]
       USE input-file-2 . . .
       GIVE output-file RECORD [record definition] ORG [file organization]

General Rules:

The RECORD and ORG Clauses are required for the first input file.
Subsequent input files are required to have the same Format and Organization, so this information does not have to be repeated.

Examples:

Sort a file in EBCDIC order

       >CITSORT SORT-EBCDIC FIELDS (1,2,NU,D) USE PRESIDENTS.DAT RECORD F 85 
       GIVE BBB.TXT ORG LSD

CitSORT MERGE functionality

The MERGE function can be used to combine two or more files that have identical record formats, and have both been Sorted on the same key, or keys.

General Format:

       USE input-file-1 RECORD [record definition] ORG [file organization]
       USE input-file-2 . . .
       SORT FIELDS ({start-pos,length,[data-type], sort-order}...)
       [FORMAT=data-type]
       GIVE output-file RECORD [record definition] ORG [file organization]

General Rules:

The RECORD and ORG Clauses are required for the first input file.
Subsequent input files are required to have the same Format and Organization, so this information does not have to be repeated.

Examples:

Merge two files sorted on the same key into a single file

       >CITSORT USE PRESMERGE1.TXT RECORD F 85 ORG LS USE PRESMERGE2.TXT 
       SORT FIELDS=(1,2,NU,A) 
       GIVE ALLPRES.TXT ORG LS

CitSORT COPY functionality

The COPY function creates a new data set which is the duplicate of the original data set.

General Format:

[Fields=]COPY

General Rules:

The file named in the USE clause is duplicated in the file named in the GIVE clause.
Multiple GIVE clauses are allowed, allowing the COPY function to duplicate a single file in multiple files.

Examples:

To create a copy of an existing file

       >CITSORT FIELDS=COPY USE PRESIDENTS.DAT RECORD F 85 
       GIVE TESTOUT.DAT

To create multiple copies of an existing file

       >CITSORT COPY USE PRESIDENTS.DAT RECORD F 85 
       GIVE TESTOUT.DAT GIVE TESTOUT2.DAT

To convert a fixed length C-ISAM file to a COBOL-IT VBISAM file

A fixed length C-ISAM file is basically a sequential file with a linefeed (x”0A”) character added to the end of each record. When a record is deleted the linefeed character is replaced with a x”00” character.

The command file shown below declares the C-ISAM file as a sequential file with a length of 40. That’s the ISAM record length of 39 plus the ending character. It then uses “OMIT COND” to detect deleted records by checking for the x”00” character at the end of each record. It declares the COBOL-IT ISAM file with a key of the first 9 bytes of the record.

       >CITSORT COPY USE CISAMFILE.DAT ORG SQ
       RECORD F 40
       OMIT COND=(40,1,CH,EQ,X'00') INREC FIELDS (1,39)
       GIVE VBISAMFILE F 39 ORG IX
       KEY (1,9,P)
       ERROR VGCITERRORFILE.TXT ORG SQ

Sorting a C-Tree File using EXTFH

The Use File and Give File are both indexed files.

The EXTFH driver for C-Tree indexed files must be used to operate the sort on the C-Tree file that is described in the USE and GIVE clauses. Set the following environment variables:

COB_CTREE_PATH=C:\FairCom\V10.4.0.RTG\winX64\Driver\ctree.cobol\EXTFH
COB_EXTFH=CTEXTFH
COB_EXTFH_LIB=C:\FairCom\V10.4.0.RTG\winX64\Driver\ctree.cobol\EXTFH\CTEXTFH.dll;$COBOLITDIR\bin\libcitextfh_dll.dll

Then, run your command:

       citsort use ABTL ORG IX KEY=(3,4,P,3,2,AD,49,1,C) RECORD F 282 
       SORT FIELDS (7,10,CH,A) 
       GIVE ausg.txt ORG IX

Dumping a C-Tree File into a Line Sequential File using EXTFH

The Use File is an indexed file and the Give file is a Line Sequential file.

The EXTFH driver for C-Tree indexed files must be used to open and read the C-Tree file that is described in the USE clause. The COB_EXTFH_LIB and the EXTFH driver for Flat Files must be used to write the Line Sequential file in the GIVE clause. Set the following environment variables:

COB_CTREE_PATH=C:\FairCom\V10.4.0.RTG\winX64\Driver\ctree.cobol\EXTFH
COB_EXTFH_INDEXED=CTEXTFH
COB_EXTFH_FLAT=EXTFH
COB_EXTFH_LIB=C:\FairCom\V10.4.0.RTG\winX64\Driver\ctree.cobol\EXTFH\CTEXTFH.dll;$COBOLITDIR\bin\libcitextfh_dll.dll

Then, run your command:

       citsort use ABTL ORG IX KEY=(3,4,P,3,2,AD,49,1,C) RECORD F 282 
       SORT FIELDS (7,10,CH,A) 
       GIVE out.txt ORG LS

CitSORT TAKE [ command-file ]

CitSORT take [command-file] provides the convenience of storing CitSORT commands in a text file. The TAKE Statement allows for the storage of CitSORT commands in a text file, in which they can be formatted with comments, and more easily maintained.

General Format:

take [ sort-command-file ]

Syntax:

Sort-command-file is a text file that contains CitSORT commands.

General Rules:

The CitSORT commands in sort-command-file may contain comments, which are preceded by an “*” asterisk.
The CitSORT commands may be separated by line terminators (LF, or CR/LF).

Examples:

CitSORT TAKE functionality

>CITSORT TAKE PRESIDENT-PARAMS.TXT

As an example president-params.txt contains:

Command	Description
`Use presidents.dat`	Identifies the file to be sorted.
`Record F 85`	Fixed length, 85 bytes, line seq.
`Sort Fields (1,2,nu,d)`	Sort key bytes 1-2/descending.
`order Give pres2.txt org ls`	Output to `pres2.txt`, line seq.