Summary

chmod +x hxsm700 hhnsinst
./hhnsinst ./hxsm700

hhnsinst.exe hxsm700.exe

hxsm700 your-parmfile

hxsm700 -vv your-parmfile

hxsm700 -v -c your-parmfile

 hxsm700
   or
 hxsm700 -h
   or
 hxsm700 --help

 hxsm700 --version

export XSM_PARM_DIR=/opt/xsm/parmfiles
export XSM_INPUT_DIR=/data/in
export XSM_OUTPUT_DIR=/data/out
export XSM_SORTWORKS_DIR=/work1/xsm,/work2/xsm

hxsm700 -vv job01.xsm

set "XSM_PARM_DIR=C:\XSM\parmfiles"
set "XSM_INPUT_DIR=D:\data\in"
set "XSM_OUTPUT_DIR=D:\data\out"
set "XSM_SORTWORKS_DIR=E:\xsmwork,F:\xsmwork"

hxsm700.exe -vv job01.xsm

    SORT/MERGE statement    - mandatory  if not OPTION COPY
    RECORD statement        - mandatory
    INPFIL statement        - optional
    OUTFIL statement        - optional
    OUTREC statement        - optional
    INCLUDE statement       - optional
    EXCLUDE|OMIT statement  - optional
    OUTFILDUP statement     - optional
    SORTWORKS statement     - optional
    IOERROR statement       - optional
    STORAGE statement       - optional
    OPTION statement        - optional

# this is a comment
* this is a comment
; this is a comment
 INPFIL /tmp/data/myinput.file        ; this is a comment for my input file

 SORT or MERGE     FIELDS=(start,length,type,direction[,start,len,type,direction,..])
                     or
                   FIELDS=(start,len,direction[,start,len,direction,..]),FORMAT=type
                     or
                   FIELDS=ALL
                     or
                   VFIELDS=(start,len,type,dir.[,start,len,type,dir.,..]),FIELDSEP=car

       start     : start column of sort field if fixed field (FIELD=)
                   field number if variable fields (VFIELDS=)

       length    : sort field length (FIELDS)
                   sort field max length (VFIELDS)

       type      : B or BI (Binary)      - binary field
                   C or CH (Char)        - normal ASCII characters (default)
                   I (Ignore case)
                   N or NU (Numeric)     - only '0' .. '9' characters (VFIELDS only)
                   P or PD (Packed)      - Packed decimal field
                                           (Binary files only, last half byte = sign)
                   Y or Y2K (yy)         - 2 bytes numeric field containing year of a date
                                           (would contain '84' for year 1984). Pivot year (option Y2KSTART,
                                           defaut 1970) is used to determinate if a year, for instance 17,
                                           means 1917 or 2017.  (see Y2K faq)

                                           
                                           
       direction : A (Ascending order), D (Descending order)

       FORMAT    : short form to use only when all sort keys have the same type
                   Thus, following statement
                        SORT FIELDS=(14,10,CH,A,24,10,CH,A)
                   can be simplified as
                        SORT FIELDS=(14,10,A,24,10,A),FORMAT=CH

       FIELDSEP  : The field delimiter/separator FIELDSEP sub-parameter value can be a symbolic name,
                   or a single character, or an hexadecimal value.

                   Using symbolic name is recommended for general punctuation chars to avoid syntax parsing
                   errors, specially with comments markers ';', '#'.

                   Symbolic names accepted:
                      BAR         =  the '|'  char
                      TAB         =  the Tabulation (X'09') char
                      COMMA       =  the ',' char
                      COLUMN      =  the ':' char
                      DIARESIS    =  the '#' char
                      SLASH       =  the '/' char
                      BACKSLASH   =  the '\' char
                      SEMICOLUMN   or SEMI-COLUMN   = the ';' char
                      SINGLEQUOTE  or SINGLE-QUOTE  = the "'" char
                      DOUBLEQUOTE  or DOUBLE-QUOTE  = the '"' char

                   Hexadecimal value: X'hh'
                      (Hex syntax : UPPERCASE X, Singlequote, 2 Hex digits, Singlequote)

                   Default value is TAB

                   Examples:
                      VFIELDS=(.....),FIELDSEP=SEMI-COLUMN
                      VFIELDS=(.....),FIELDSEP=@
                      VFIELDS=(.....),FIELDSEP=              ; Field separator is space char
                      VFIELDS=(.....),FIELDSEP=X'7C'
                      VFIELDS=(.....)                        ; Default Field separator is TAB


Command-line equivalent: --sort / --merge --key=

 SORT FIELDS=(17,3,B,D,1,15,B,A)
     or
 SORT FIELDS=(17,3,BI,D,1,15,BI,A)
     or
 SORT FIELDS=(17,3,D,1,15,A),FORMAT=BI

 SORT FIELDS=(2,4,B,A) ; sorts a 4-byte binary integer in Descending order
 SORT FIELDS=(6,2,B,D) ; will sort a short (16 bits) in Ascending order
 SORT FIELDS=(2,8,B,A) ; will sort a long (8x8=64 bits) in Descending order (created on a 64-bits OS)

 SORT FIELDS=(12,20,I,A)

 SORT FIELDS=(7,4,P,D)  ;  7 BCD digits, with sign

 SORT VFIELDS=(12,20,I,A,7,9,N,D),FIELDSEP=:

 SORT VFIELDS=(12,20,I,A,7,9,N,D),FIELDSEP=

 SORT VFIELDS=(12,20,I,A,7,9,N,D),FIELDSEP=TAB
    or
 SORT VFIELDS=(12,20,I,A,7,9,N,D)  ;   FIELDSEP=TAB implied (default)

 SORT FIELDS=(25,2,Y,D,21,2,B,D,23,2,B,D)

 SORT FIELDS=ALL

  RECORD RECFM=record format,LRECL=record length

   record format : F  for Fixed,
                   V  for Variable
                   T  for Text   (V and T are equivalent)
                   M  for MicroFocus "MFCOBOL"" or "MFVariable"

   record length : Exact record length for RECFM=F, including any separator CR/LF
                   Maximum record length for RECFM=V, excluding line separator CR/LF
				   
Equivalent command-line parameter: --recfm= --lrecl=

 RECORD RECFM=F,LRECL=400

 RECORD RECFM=V,LRECL=133

 INPFIL filename
 
        filename   : input file name

Command-line equivalent: --infile=

 INPFIL DD:varname
 
           varname   : Environment variable name holding input filename.

 INPFIL C:\Myjob\BIGF.INP             # Windows
 INPFIL D:\TMP\Wrk.Dat                # Windows

 INPFIL /home/hh/bigf.inp             # UNIX
 INPFIL /home/hh/littlef.inp          # UNIX

 INPFIL DD:SORTIN1                    # any systems
 INPFIL DD:SORTIN2                    # any systems
 INPFIL DD:JOHNNY                     # any systems

# SORTIN1, SORTIN2, and JOHNNY are environment variables containing filenames

 OUTFIL filename[,INCLUDE/EXCLUDE=(condition1,[AND/OR,condition2...)]
                [,RECFM=recfm][,LRECL=lrecl][,DISP=disp]
                
        filename   : output file name

        condition  : start,length,datatype,operator,pattern

                     start     : start pos of zone to compare
                     length    : length of zone to compare
                     type      : 'CH' (Char) or 'BI' (Binary)
                     operator  : EQ or NE or LT or LE or GT or GE
                     pattern   : C'cccc' where cccc = string to compare
                                 X'xxxx' where xxxx = hexadecimal string to compare
                                 N'nnnn' where nnnn = numeric value to compare

                                Length of string must equal length of zone to compare

        recfm :     output record format if different of the input one :
                    RECFM=V or RECFM=F


        lrecl :     output logical record length if different of the input one.
                    For RECFM=V (variable), record is truncated if output LRECL is smaller than input LRECL
                    Pour RECFM=F, truncate record of smaller than input LRECL,
                          add padding if larger that input LRECL


        disp :      "Disposition"  in case output file exists before XSM starts :
                       DISP=NEW       : abort of output file already exists
                       DISP=OVERWRITE : overwrites output file (default)
                       DISP=APPEND    : "Appends" if output file already exists

                       
Command-line equivalent: --outfile=

OUTFIL DD:varname[,INCLUDE/EXCLUDE=(condition1,[AND/OR,condition2...)]
                  [,RECFM=recfm][,LRECL=lrecl][,DISP=disp]

           varname   : Environment variable name containing output filename.

 OUTFIL FILE=nn[,INCLUDE/EXCLUDE=(condition1,[AND/OR,condition2...)]
                      [,RECFM=recfm][,LRECL=lrecl][,DISP=disp]

        FILEnn associates environmet variable SORTOFn where nn is an integer greater than 0.

Example :

 OUTFIL FILE=01,INCLUDE=(8,2,CH,EQ,75)       ; variable SORTOF1 for Paris department
 OUTFIL FILE=02,INCLUDE=(8,2,CH,EQ,14)       ; variable SORTOF2 for Normandie department
 OUTFIL FILE=971,INCLUDE=(7,3,CH,EQ,971)     ; variable SORTOF971 For Guadeloupe department
 ...

 OUTFIL D:\TMP\BIGF.OUT                                  ;  Windows full pathname style, no filters

 OUTFIL /home/hh/bigf.out                                ;  UNIX full path name style, no filters

 OUTFIL DD:FOO                                           ; using FOO environment variable FOO, no filters

 OUTFIL DD:FOO2,EXCLUDE=(11,3,CH,EQ,C'POP')    ; drop records that match 'POP' in column 11

 OUTFIL /data1/clients1.dat,EXCLUDE=(11,3,CH,EQ,C'POP') ; same, but with hard coded filename
                                                         ; instead of a variable

 OUTFIL DD:XYZ1,INCLUDE=(11,3,CH,EQ,C'MAR',
                          OR,
                         11,3,CH,EQ,'GAS')               ; only write records that match 'MAR' or 'GAS' 
                                                         ; at column 11

Note : Do not insert comments inside a conditional clause !

            NONE                     ; nothing suppressed (default, for IBM D/SORT compatibility)

            DUPLICATE KEYS           ; suppress all lines/recordsa with duplicate sort keys
         or DUPKEYS                  ; equivalent to DFSORT SUM FIELDS=NONE de DFSORT.
 OMIT    or DUPKEY

            DUPLICATE RECORDS        ; suppress duplicate lines/records
         or DUPRECORDS
         or DUPRECORD
         or DUPRECS
         or DUPREC
         
Command-line equivalent: --unique-key / --unique-record

 INCLUDE
 EXCLUDE     COND=(column,length,type,operator,pattern[,AND|OR,col,len,type,oper,pattern,...])
 OMIT

      col        : start position of the field to be examined in each record (1..n)
      
      len        : field length
      
      type       : always 'CH' (useless but for IBM SORT compatibility...)
      
      operator   : one of 'EQ' 'NE' 'GT' GE' 'LT' 'LE'
      
      pattern    : constant C'ccccc...' where ccccc is characters string
                            X'xxxxx...' where xxxxx is hexadecimal value
               from v6.92 : N'nnnnn...' where nnnnn is numeric value
               from v6.93 : nnnnn...    where nnnnn is numeric value

               
Command-line equivalent: --include= / --exclude=               

  INCLUDE COND=(1,5,CH,GT,N'100')
  INCLUDE COND=(1,5,CH,LT,N'500')

  INCLUDE COND=(1,5,CH,GT,100,AND,1,5,CH,LT,500)

 OUTFIL   DD:variable,INCLUDE|EXCLUDE=(col,len,type,op,pattern[,AND|OR,col,len,type,op,pattern ...])

 from v6.92 :
 OUTFIL   pathname,INCLUDE|EXCLUDE=(col,len,type,op,pattern[,AND|OR,col,len,type,op,pattern ...])

 INCLUDE COND=(15,5,CH,EQ,C'JONES',OR,15,5,CH,EQ,C'SMITH')
 OMIT    COND=(11,3,CH,EQ,C'000')

SORT    VFIELDS=(9,2,C,A,8,30,C,A,10,5,N,A),FIELDSEP=COMMA
RECORD  RECFM=V,LRECL=400

; ----------------  all clients:
OUTFIL  DD:ALLCLIENTS
; ----------------  only clients from New-York:
OUTFIL  DD:NEWYORKERS,INCLUDE=(9,2,CH,EQ,C'NY')
; ----------------  Client not in New-York:
OUTFIL  D:\data\app1\others.csv,EXCLUDE=(9,2,CH,EQ,C'NY')
; ----------------  only clients from Washingtown whose name start with AB, CD, or EF :
OUTFIL  DD:WASHDC,INCLUDE=(9,2,CH,EQ,C'WA',AND,
                              (11,2,CH,EQ,C'AB',OR,
                               11,2,CH,EQ,C'CD',OR,
                               11,2,CH,EQ,C'EF'))

    OUTFILDUP  /my/duplicate.file.txt

      ou

    OUTFILDUP  DD:Myvariable

Command-line equivalent: --outfiledup=

  OUTREC  FIELDS=(start,length[,start2,len2...])
  
                 start    : start position 
                 
                 length   : field length
                 
command-line equivalent: --outrec=

 OUTREC  FIELDS=(start,length,type,offset[,start2,len2,type2,offset2...])
 
                 start    : start position or padding value when type=B, P, or Z
                 
                 length   : field length
                 
                 type  C  : normal field to copy
                       S  : space padding 
                       B  : byte : padding with value specified as 'start' 
                       P  : Packed Decimal : Packed Decimal padding with value specified as 'start'
                       Z  : Zone Decimal : Packed Decimal padding with value specified as 'start'
                       
                 offset : output position

  OUTREC FIELDS=(C'A',10,B,33)
  OUTREC FIELDS=('A',10,B,33)
  OUTREC FIELDS=(A,10,B,33)
  OUTREC FIELDS=(X'45',10,B,33)
  OUTREC FIELDS=(X45,10,B,33)
  OUTREC FIELDS=(65,10,B,33)
  OUTREC FIELDS=(D65,10,B,33)
  OUTREC FIELDS=(D'65',10,B,33)
  OUTREC FIELDS=(N65,10,B,33)
  OUTREC FIELDS=(N'65',10,B,33)

OUTREC FIELDS=(1,5,C,1,
               2,5,C,12)

John;Smith;;123;

John;;;;;;;;;;;;Smith;

  RECORD  RECFM=V,LRECL=300       ; input file specification
  ...
  OUTFIL DD:OUTNORMAL             ; this file will use the input LRECL=300
  OUTFIL DD:OUT_L40,LRECL=40     ; this file will have max 40 char record length
  OUTFIL DD:OUT_L100,LRECL=100   ; this file will have max 100 char record length

  SORT FIELDS=(10,12,C,A)                        ; sort keys on pos 10, length 12, Character, Ascending
  RECORD RECFM=V,LRECL=200                       ; input is variable length records ended with LR or CR/LF

  INPFIL  /usr/include/stdint.h                  ; input file
  
  IOERROR IGNORE                                 ; get rid of empty lines
  
  OUTFIL DD:SORTOUT,INCLUDE=(3,6,C,EQ,C'define') ; filters only ""# define ..." lines

  OUTREC FIELDS=(10,12,C,20)                ; puts zone 10 to 21 at position 20

/* Limits of integral types.  */

/* Minimum of signed integral types.  */
# define INT8_MIN               (-128)
# define INT16_MIN              (-32767-1)
# define INT32_MIN              (-2147483647-1)
# define INT64_MIN              (-__INT64_C(9223372036854775807)-1)
 ...

                   INTMAX_MAX
                   INTMAX_MIN
                   INT_FAST64_M
                   INT_FAST64_M
                   INT_FAST8_MA
                   INT_FAST8_MI
                   INT_LEAST16_
                   INT_LEAST16_
 ...

 OUTREC  FIELDS=('-',10,B,1,
                  10,12,C,20)

----------         INTMAX_MAX
----------         INTMAX_MIN
----------         INT_FAST64_M
----------         INT_FAST64_M
----------         INT_FAST8_MA
----------         INT_FAST8_MI
----------         INT_LEAST16_
----------         INT_LEAST16_
 ...

 OUTREC  FIELDS=('-',10,B,1,
                  10,12,C,20,
                  X'0A',1,B,23)

----------         INT
MAX_MAX
----------         INT
MAX_MIN
----------         INT
_FAST64_M
----------         INT
_FAST64_M
----------         INT
_FAST8_MA
----------         INT
_FAST8_MI
----------         INT
_LEAST16_
----------         INT
_LEAST16_
 ...

 SKIP_HEADER nnn
 SKIP_HEADERS nnn

Command-line equivalent: --skip-header=   --skip-headers=

 SKIP_HEADER 4  # ignore 4 premières lignes d'entete du fichier

 OPTION  option1,option2,...
    or
 OPTIONS  option,option,...

 OPTION RSEP=|
  or
 OPTION RSEP=7C

 OPTION PROCS=8

 OPTION COPY
   or
 SORT FIELDS=COPY
   or
 COPY
 
Command-line equivalent: --copy

 OUTFIL DD:variable                    ; equivalent to OUTFIL DD:variable,INCLUDE=ALL
   or
 OUTFIL DD:variable,INCLUDE|EXCLUDE=(condition1[,AND/OR,condition2...])

  OMIT DUPKEYS

  #  Output file, deduplicated:
  OUTFIL     myoutput.txt

  # output file with duplicate records:
  OUTFILDUP  myduplicate.txt

  #  this is to write also first record that compared to duplicate
  OPTION WRITEFIRSTDUPLICATE

  
Command-line equivalent: --outfiledup-record1 ou --dup-rec1

01234001 JOHN     PALMER
05678001 BOB      JOHNSON
01234002 JOHN     PALMER
05678002 BOB      JOHNSON
06095300 KAREN    SMITH

01234002 JOHN     PALMER
05678002 BOB      JOHNSON

05678001 BOB      JOHNSON
05678002 BOB      JOHNSON
01234001 JOHN     PALMER
01234002 JOHN     PALMER

Example of OPTION statement usage:

OPTION PROCS=4,KEEP_ORDER=Y      # force multithreading on 4 procs, force stable sort

The IOERROR statement

 IOERROR IGNORE

Command-line equivalent: --ignore-ioerror

The IOERROR statement is valid for variable length text (RECFM=V) files only.

It tells XSM what to do when a record is shorter than a defined key:

• if omitted, the first line shorter than the sort key will cause XSM to 'ABEND' (Abnormal end) immediately.
• if present, errors due to lines shorter than sort key will be ignored.

The SORTWORKS statement

 SORTWORKS directory[,directory,...]

           directory : one or more directory full path for temporary work files.


Command-line equivalent: --sortworks=

The SORTWORKS statement is used to control where to put work files on different drives, or UNIX file-systems (recommended)

 SORTWORKS C:\TMP,D:\TEMP   (Windows)
 SORTWORKS /var/tmp,/tmp    (UNIX)

The SORTWORKS statement is optional: if omitted, all work files are created (then deleted after use) in the current directory.

*** Using SORTWORKS properly is essential for performance ***

When more than one sortworks directory is given, XSM will force multi-threading: one thread per directory.

When OPTION PROCS= is specified together with SORTWORKS=dir1,dir2,...,dir_n, XSM will use max of both values for threads number.

Using temporary workfiles on another physical disk than the one having input/output files will dramatically improve XSM performance as it will reduce concurrent I/O on a single disk.

Indeed, to simplify, consider XSM I/O phases are:

       Phase 1 :   reading input file  +  writing sortworks
-------------------------------------------------------------------------
       Phase 2 :   reading sortworks   +  writing output file

                                          (Disk1)    (Disk2)
   Phase 1 :   reading input file          Read
             + writing sortworks                      Write
-------------------------------------------------------------------------
   Phase 2 :   reading sortworks                      Read
             + writing output file         Write

                                          (Disk1)    (Disk2)
   Phase 1 :   reading input file          Read
             + writing sortworks           Write <==  Concurrent I/O on same disk: BAD!
-------------------------------------------------------------------------
   Phase 2 :   reading sortworks                      Read
             + writing output file         Write

This illustrates the same sort operation, with one disk / with two disks:

Please note than results highly depend on factors such as filesize, free memory, disk speed, CPU speed.
Above chart just illustrates that using different physical hard disks will improve sort time with no doubt.

Temporary files are named after the current XSM Process Id, srtw04d2.xxx for instance for Pid 1234 (hexa 04d2). So running several XSM simultaneously using same SORTWORKS directories is not a problem.

Temporary files are deleted upon job completion.
In case of a severe error they may remain on disks so it is wise to check XSM return code.

See XSM sample jobs

The STORAGE statement

 STORAGE size{K|M|G}

      size      : amount of main storage to use, in Kilobytes, Megabytes, or Gigabytes.

     Examples:

            STORAGE 450K
            STORAGE 2150K
            STORAGE 8M

            Command-line equivalent: --storage=

The STORAGE statement is optional. It is calculated by XSM, depending on your Operating System and input files.

For huge files, it can be used to limit paging/swapping leading to System Stress.

        T = total input size in Megabytes
        
        T ≤ 64517 MB  :  STORAGE = square root( T ) / 4
        
        T > 64517 MB  :  STORAGE = T / 1020

For instance, 3 input files of 25000 MB:

5. Command Line Syntax

The XSM Sort/Merge program is invoked from the system command-line.

You may call XSM with or without parameter file.

Once you have manually setup XSM parameters and options, just plug the command-line in your batch program: UNIX Shell, Windows .bat or whatever is your favorite batch language.

The full syntax is displayed if you start XSM without any flag, or with --help flag :

hxsm700 [options]

Options:

  -c, --check           check result of a previous sort/merge operation and issues message
                        "XSM064I The file xxx correctly sorted" on success

  -q, --quiet           run in quiet mode with no information displayed on stderr, unless an error occurs
                        Note that stdout is reserved for default output if no output specified

  -v, --verbose         display details while processing
                        -v/--verbose and -q/--quiet are mutually exclusive

   -vv, --veryverbose   displays more details

  -h, --help            display help and exit

      --version         display the XSM version and exit   *** v7.00 ***


      --sort            sort operation (default)

                        Parmfile equivalent: SORT


  -m, --merge           merge pre-sorted files

                        Parmfile equivalent: MERGE

                        
      --copy            copy without sorting, but can filter with INCLUDE/EXCLUDE/SKIP_HEADER and reformat
                        with OUTREC.
                        
                        Parmfile equivalent: OPTION COPY
                        
                        --sort --merge --copy are mutually exclusive


  -k, --key=start,len[,direction,[type]]
                        sort key definition:                       
                        start     :  starting position (relative to 1)  for that key.
                        length    :  key length, in bytes
                        direction :  'D' = descending, 'A' = ascending
                        type      :  'C' = character
                                     'B' = binary byte ("low value" in Cobol)
                                     'I' = ignore Upper/lower case
                                     'N' = numeric
                                     'P' = Packed decimal field (RECFM=F or M files only)
                                     'Y' = Year in a date

                        Parmfile equivalent: SORT FIELDS=(start,len,dir,type)


  -k all, --key=all     sort using whole record as key

                        Parmfile equivalent: SORT FIELDS=ALL


  -r, --recfm=F|V|M     specify Record Format, can be F (Fixed), V (variable), M (MFCobol)
                        default is V (variable)

                        Parmfile equivalent: RECORD RECFM=


  -l nnn, --lrecl=nnn   specify Logical Record Length (LRECL):
                          nnn = exact record length for RECFM=F, including any separator CR/LF
                          nnn = max record length for RECFM=V, excluding line separator CR/LF

  -z nnn         same as -l nnn (for UNIX compatibility)
                       
                        Parmfile equivalent: RECORD LRECL= 
 

      --infile=file[,recfm=x[,lrecl=nnn]   specify input file(s)
                        RECFM and LRECL can be specified together with an input file when reformatting.
                        See Reformatting

                        multiple input files can be specified, as follow:
                        --infile=/tmp/f1 --infile=/tmp/f2 ...
                        
                        Parmfile equivalent: INPFIL


  -o, --outfile=fileout[,recfm=F|V|M[,lrecl=nnn]] specify output file
                        File can be specified as full file name, DD:variable, of FILE=nn  
                        (see Form 1, 2 and 3 of OUTFIL statement)
                        RECFM and LRECL can be specified together with an output file when reformatting.
                        See Reformatting
 
                        Parmfile equivalent: OUTFIL

               
      --outrec=(pos,len[,p2,l2,...])
      --outrec=(pos,len,type,offset[,p2,l2,t2,o2,...]) specify output record
                        when reformatting.
                        See Reformatting

                        Parmfile equivalent: OUTREC


  -uk, --unique-key     drop next records with duplicate keys, 1rst one is kept

                        Parmfile equivalent: OMIT DUPLICATE KEYS


  -ur, --unique-record  drop duplicate records, 1rst one is kept

                        Parmfile equivalent: OMIT DUPLICATE RECORDS
                        

      --outfiledup=fileout  writes duplicate records to a file     *** v6.94 ***

                        Parmfile equivalent: OUTFILDUP


      --outfiledup-record1  Includes first record that compares to duplicate in duplicate file.
      --dup-rec1            Without this option only next duplicate records are written to duplicate file.
                            See sample.    *** v6.94 ***

                        Parmfile equivalent: OPTION WRITEFIRSTDUPLICATE


       --include=start,len,op,val[AND|OR,start,len,op,val...] specify include filter

                        Parmfile equivalent: INCLUDE


       --exclude=start,len,op,val[AND|OR,start,len,op,val...] specify exclude filter

                        Parmfile equivalent: EXCLUDE


 -t dir1,dir2  --sortwork[s]=dir1,dir2,...    sortworks directory list
                        you can specify several directories, separated by comma (,) or
                        issue several --sortworks=  or -t :
                        
                        --sortworks=/tmp1/dir1 --sortworks=/tmp/dir2
                               equivalent to:
                        --sortworks=/tmp1/dir1,/tmp/dir2
                               equivalent to:
                        -t /tmp1/dir1 -t /tmp/dir2
                               equivalent to:
                        -t /tmp1/dir1,/tmp/dir2

                        Parmfile equivalent: SORTWORKS


  -y nnnK|M|G, --storage=nnnK|M/G force storage allocation to nnn Kilo/Mega/Gigabytes
                        in most cases, better to let XSM calculate by itself
                        to use only when slow processing on very large files

                        Parmfile equivalent: STORAGE


      --keep-order      force non-destructive sort, also called "stable sort"
                        see explanation below.

                        Parmfile equivalent: OPTION KEEP_ORDER


      --record-separator=C|0xhh  defines the characters or pair of characters at the end
                        of each record.  This option is primarily used for OPEN MVS and OS/400 for variable 
                        length files.

                        Parmfile equivalent: OPTION RECORD_SEPARATOR


      --collating-sequence=ebcdic force alphanumeric sequence to IBM's EBCDIC

                        Parmfile equivalent: OPTION COLLATING


      --skip-header=nnn  ignore nnn first records of first input file

                        Parmfile equivalent: SKIP_HEADER


      --skip-headers=nnn ignore nnn first records of all input files

                        Parmfile equivalent: SKIP_HEADERS
                        
      --throw-empty-records ignore empty records. Without this option, XSM will stop with an error if 
                         it encounters empty (length=0) record on input stream.

  -i, --ignore-ioerror  ignore lines shorter that sort keys (text file RECFM=V only)
                        
                        Parmfile equivalent: IOERROR IGNORE


  -n n, --procs=n       force multi-threading to n Threads
                        Parmfile equivalent: OPTION PROCS

      --norun           test syntax of parmfile only. does not process
      

hxsm700 --infile=/tmp/f.in --outfile=/tmp/f.out myparms.xsm

6. Sample sort jobs: The best way to get into!

Job 1 : Single text file

• The largest expected line is 200 char. long (excluding the trailing CR/LF)
• The sort key is a char field starting col 14 to 20. Key length = 20 - 14 + 1 = 7
  Input file looks like:

  0         1   1     2         3
  0123456789012345678901234567890123456 ...
  |....+....|....+....|....+....|....+.....
  ABCDEF PARIS  001HHNS  A123456 2010-12-31...
                [ key ] : starts col 14, ends col 20
  

• The input file is 'SAMPLE.INP'
• The output file is 'SAMPLE.OUT'

Method 1: input/output files are specified using UNIX style redirections

 hxsm700 --recfm=V --lrecl=200 --key=14,7,A  < SAMPLE.INP > SAMPLE.OUT
 
       or 
       
hxsm700 -r V -l 200 -k 14,7,A  < SAMPLE.INP > SAMPLE.OUT        

 hxsm700 job1.xsm  < SAMPLE.INP > SAMPLE.OUT

 SORT     FIELDS=(14,7,C,A)      ; one sort key in position 14, length 7, type Char, Ascending
 RECORD   RECFM=V,LRECL=200      ; Variable length, maximum expected length is 200

Method 2: input/output files are "hard coded" in parmfile

 SORT     FIELDS=(14,7,B,A)      ; one sort key in position 14, length 7, type Binary, Ascending
 RECORD   RECFM=V,LRECL=200      ; Variable length, maximum expected length is 200
 INPFIL   SAMPLE.INP           ; Input file
 OUTFIL   SAMPLE.OUT           ; Output file

 hxsm700 -vv job1.xsm

Method 3: Command-line without parmfile:

 hxsm700 -vv -k 14,7 -l 200 < SAMPLE.INP > SAMPLE.OUT
 
    or
    
 hxsm700 -vv -k 14,7 -l 200 -o SAMPLE.OUT   SAMPLE.INP
 
    or
    
 hxsm700 -vv --key=14,7 --lrecl=200 --outfile=SAMPLE.OUT --infile=SAMPLE.INP

Job 2 : Single text file, redirecting stdout stream

• Same as above, but the output will be redirected to a report program named 'MYREPORT.EXE'

# Job 2 : OUTFIL is not specified, so XSM will output on stdout
#        This is used to redirect output to another program
 SORT     FIELDS=(14,7,B,A)
 RECORD   RECFM=V,LRECL=200
 INPFIL   SAMPLE.INP

 hxsm700 -vv job2.xsm | myreport

 hxsm700 -vv -k 14,7 -i SAMPLE.INP | myreport

 hxsm700 -vv -ur -k 14,7 -i SAMPLE.INP | myreport
 
   or
   
 hxsm700 -vv --unique-record --key=14,7 --infile=SAMPLE.INP | myreport

Job 3 : Single text file, redirecting stdin, stdout streams

• Same as above, but the input comes from an accounting program named 'MYACCOUNT.EXE'

# Job 3 : neither INPFIL nor OUTFIL are specified:
#         UNIX style redirections are used instead
 SORT     FIELDS=(14,7,B,A)
 RECORD   RECFM=V,LRECL=200

 myaccount | hxsm700 job3.xsm | myreport

 myaccount | hxsm700 -k 14,7  | myreport

Job 4 : Two Binary files, sortworks on distinct disks for I/O optimization

• All records are 180 char. long
• The sort key is an account number col 14 to 20, plus a date (yymmdd) col 2 to 7
• For each account, records are to be sorted on decreasing date
• The input files are '../s1' and '../s2', each about 4 Megabytes large
• The output file is '/usr/acct/sample.out'
• The second drive is mounted as /var so we use 2 sortwork directories on 2 distinct disks for I/O optimization.
  See Sortworks discussion to understand benefit.

# job4.xsm  : XSM parameter file for job4
#------------  Sort keys :
 SORT      FIELDS=(14,20,B,A,2,6,B,D)
 RECORD    RECFM=F,LRECL=180
 
#------------  input/output files: 
 INPFIL    ../s1                              ; input file #1
 INPFIL    ../s2                              ; input file #2
 OUTFIL    /usr/acct/sample.out               ; output file 
 
#------------  temp files : 
 SORTWORKS /drive1/tmp,/drive2/tmp            ; 2 sortwork directories
 

 hxsm700 -vv job4.xsm

 hxsm700 -vv -k 14,20 -k 2,6,d -r F -z 180             \
      -t /var/tmp,/tmp                          \
      -o /usr/acct/sample.out ../s1 ../s2

 hxsm700 -vv  --key=14,20   --key=2,6,d   --recfm=F   --lrecl=180    \
        --sortwork=/var/tmp,/tmp                                  \
        --outfile=/usr/acct/sample.out                            \
        --infile=../s1    --infile=../s2

Job 5 : Two Binary files, filtering records with OMIT

• Same as above, but only records which do not start with a '*' are to be processed

# job5.xsm  : XSM parameter file for job5
#------------  Sort keys :
 SORT      FIELDS=(14,20,B,A,2,6,B,D)
 RECORD    RECFM=F,LRECL=180
 
#------------  input/output files: 
 INPFIL    ../s1                              ; input file #1
 INPFIL    ../s2                              ; input file #2
 OUTFIL    /usr/acct/sample.out               ; output file 
 
#------------  temp files : 
 SORTWORKS /drive1/tmp,/drive2/tmp            ; 2 sortwork directories
 
#------------  filters :
 OMIT        COND=(1,1,CH,EQ,'*')             ; exclude records with character '*' on position 1

 hxsm700 job5.xsm

 
 hxsm700   --key=14,20   --key=2,6,d   --recfm=F   --lrecl=180     \
        --sortwork=/var/tmp,/tmp                                \
        --outfile=/usr/acct/sample.out                          \
        --infile=../s1    --infile=../s2                        \
        --exclude="1,1,C,'*'"

Job 6 : CSV Text File with variable field length and field separator

• Line size is maximum 100 chars, excluding UNIX LF or Windows CR/LF
• 1st key: a name, 3rd field, max length 40 bytes, ignore case, ascending
• 2nd key: a number, 2nd field, max length 10 digits (char '0' .. '9'), descending
• Drop lines with duplicate keys, except the 1st one

 SORT      VFIELDS=(3,40,I,A,2,10,N,D),FIELDSEP=SEMICOLUMN  ; Variable length fields delimited by ';'
 RECORD    RECFM=T,LRECL=100
 INPFIL    ../s1
 OUTFIL    /usr/acct/sample.out
 OMIT      DUPKEYS               ; short for OMIT DUPLICATE KEYS

Note: Defining Field Separator with symbolic keywords SEMICOLUMN, COMMA, etc... is recommended to avoid syntax parsing errors, specially with comments markers ';', '#'. See FIELDSEP= syntax.

 hxsm700 job6.xsm

Job 7 : Binary file with Packed Decimal zones

• Record length is 110 bytes,
• 1st key from pos. 1 to 4, "Packed Decimal", descending order,
• 2nd key from pos. 21 to 40, Alphanumerical, ascending order.

 SORT      FIELDS=(1,4,P,D,21,20,B,A)           ; type P means Packed decimal
 RECORD    RECFM=F,LRECL=110
 INPFIL    E:\tmp\s1.bin
 OUTFIL    E:\tmp\s2.bin

 hxsm700 job7.xsm

 hxsm700 -r F -l 110 -k 1,4,P,D -k 21,20 -o E:\tmp\s2.bin E:\tmp\s1.bin

 hxsm700 --recfm=F  --lrecl=110 --key=1,4,P,D --key=21,20 --outfile=E:\tmp\s2.bin --infile=E:\tmp\s1.bin

Job 8 : Text file with date field 'mmddyy', changing Y2K century pivot

• text lines are at most 110 bytes long, excluding the trailing CR/LF,
• 1st key pos. 1-4, Alphanumeric, ascending order,
• 2nd key pos. 21-40 Alphanumeric, ascending order,
• 3rd key pos. 61-66 date like 'mmddyy', descending order
• the oldest date is past the year 1970 (default Y2K pivot).

 SORT      FIELDS=(1,4,BI,A,21,20,BI,A,65,2,Y2K,D,63,2,BI,D,61,2,BI,D)
 RECORD    RECFM=V,LRECL=110
 INPFIL    /tmp/s1.txt
 OUTFIL    /tmp/s2.txt

 hxsm700 job8.xsm

 OPTION Y2KSTART=19nn

 Example:
 OPTION Y2KSTART=1963   # changing Y2K pivot from 1970 to 1963

Job 9 : Several text input files with identification and removal of duplicate records

• Text lines are at most 100 bytes long, excluding the trailing CR/LF,
• Records with duplicate keys are removed
• We merge a monthly file and daily file for input

00001    PALMER    JOHN      0012343445T46767878
00002    JOHNSON   BOB       04E3293223235454654
00003    SMITH     KAREN     0012343345665766887
00004    PALMER    MIKE      0432434545657675606
00005    SMITH     JACK      0046546507675465778

00001    PALMER    MIKE      0432434545657675606
00002    SMITH     KAREN     0012343345665766887
00003    WOOD      PAUL      0343256556560767657

#0001    PALMER    JOHN
#        |         |
#        pos 10    pos 20
#             |         |
 SORT FIELDS=(10,10,C,A,20,10,C,D)                 # sort keys : Last Name, First Name
 RECORD RECFM=V,LRECL=100

# Adds daily data to monthly data :
 INPFIL     data.monthly.2020.04.txt               #  Monthly input
 INPFIL     data.daily.2020.04.05.txt              #  Daily input

 OUTFIL     data.monthly.deduplicated.2020.04.txt  # Montly deduplicated data

 OMIT DUPLICATE KEYS
 OUTFILDUP  data.monthly.duplicated.2020.04.txt    # Montly duplicated data

 hxsm700 -vv dedup.xsm

  
hxsm700 -vv --recfm=V --lrecl=100 --key=10,10,A --key=20,10,D   \
       --infile=data.monthly.2020.04.txt                     \
       --infile=data.daily.2020.04.05.txt                    \
       --outfile=data.monthly.deduplicated.2020.04.txt       \
       --unique-key                                          \
       --outfiledup=data.monthly.duplicated.2020.04.txt

XSM056I HXSM V7.00-64 - (C) HH&S 2002-2026, Build Aug 1 2026
XSM096I Parameter file dedup.xsm loaded. 7 valid statements
XSM096I   key # 1 start   10, len  10, order ASCEND , type CHAR
XSM096I   key # 2 start   20, len  10, order DESCEND, type CHAR
XSM027I Initializing ...
XSM096I Using 2 nCPU, 4 Threads
XSM089I Memory Total 2005 MB, Free 1614 MB
XSM024I Using 0 work dir., 1 x 176 KB
XSM028I Reading
XSM073I            8 records processed, so far            8      :       0 sec.
XSM015I Input:   ---------------------------------------------------------------
XSM014I            5 rec read from  data.monthly.2020.04.txt
XSM014I            3 rec read from  data.daily.2020.04.05.txt
XSM014I            8 rec read total
XSM015I Filters: ---------------------------------------------------------------
XSM014I            2 rec dropped on duplicate key
XSM015I Output:  ---------------------------------------------------------------
XSM014I            2 rec with duplicate key written to data.monthly.duplicated.2020.04.txt
XSM014I            6 rec written to data.monthly.deduplicated.2020.04.txt
XSM014I            6 rec written total
XSM031I End of Job dedup.xsm                              6 rec. :       0 sec.

00002    JOHNSON   BOB       04E3293223235454654
00001    PALMER    MIKE      0432434545657675606
00001    PALMER    JOHN      0012343445T46767878
00003    SMITH     KAREN     0012343345665766887
00005    SMITH     JACK      0046546507675465778
00003    WOOD      PAUL      0343256556560767657

00004    PALMER    MIKE      0432434545657675606
00002    SMITH     KAREN     0012343345665766887

 OPTION WRITEFIRSTDUPLICATE

Job 10 : Copy a text file and selective split onto several output files

• input and output file names are set using environment variables
• text lines are at most 152 bytes long, excluding the trailing CR/LF
• all lines are copied onto file # 1
• lines beginning with name 'SCOTT' and containing 'TIGER' in cols. 16-20 are written onto output file # 2
• other lines are written onto output file # 3
• ddname for input file is SORTIN (could be any other variable name)
• ddnames for output files are SORTOF1, SORTOF2, SORTOF3. (syntax: SORTOF + a number, starting at 1)

Note the use of DD:varname which needs initialization of environment variable varname

DD:varname form can be used both for INPFIL and OUTFIL statements

 OPTION    COPY
 RECORD    RECFM=V,LRECL=152  ; excluding CR/LF
 INPFIL    DD:DATAIN
 OUTFIL    DD:DATAOUT1,INCLUDE=ALL
 OUTFIL    DD:DATAOUT2,INCLUDE=(1,5,CH,EQ,'SCOTT',AND,16,5,CH,EQ,'TIGER')
 OUTFIL    DD:DATAOUT3,INCLUDE=(1,5,CH,NE,'SCOTT',OR,16,5,CH,NE,'TIGER')
 OMIT      DUPRECS

 DATAIN=/tmp/myappl/data_to_copy.text \
 DATAOUT1=/tmp/s1                      \
 DATAOUT2=/tmp/s2                      \
 DATAOUT3=/tmp/s3                      \
 hxsm700 -vv job10.xsm

 
 setlocal
 set DATAIN=C:\tmp\myappl\data_to_copy.text
 set DATAOUT1=D:\tmp\s1       (or \tmp\s1 ...)
 set DATAOUT2=D:\tmp\s2
 set DATAOUT3=D:\tmp\s3
 hxsm700 -vv job10.xsm

No full command-line equivalent for this job, due to DD:varname,INCLUDE=(...) forms.

• Same as job 10 above but using a sort operation (SORT FIELDS= statement) instead of a copy operation (OPTION COPY statement):

Parameter File job11.xsm:

 SORT      FIELDS=(1,5,C,A,16,5,C,A)
 RECORD    RECFM=V,LRECL=152  ; sans compter CR/LF
 INPFIL    DD:SORTIN
 OUTFIL    DD:OUT1,INCLUDE=ALL
 OUTFIL    DD:OUT2,INCLUDE=(1,5,CH,EQ,'SCOTT',AND,16,5,CH,EQ,'TIGER')
 OUTFIL    DD:OUT3,INCLUDE=(1,5,CH,NE,'SCOTT',OR,16,5,CH,NE,'TIGER')
 OMIT      DUPRECS

 SORTIN=/tmp/myappl/data_to_split.text \
 OUT1=/tmp/s1                       \
 OUT2=/tmp/s2                       \
 OUT3=/tmp/s3                       \
 hxsm700 -vv job11.xsm

No full command-line equivalent for this job, due to DD:varname,INCLUDE=(...) forms.

Job 12 : Sort/Merge files and selective split onto several output files

• Same as job 11 above but using 3 input files instead of one:

Parameter File job12.xsm:

 SORT      FIELDS=(1,5,C,A,16,5,C,A)
 RECORD    RECFM=V,LRECL=152  ; excluding CR/LF
 INPFIL    DD:MYINPUT1        ; variable name is free with DD: form
 INPFIL    DD:MYINPUT2        ; variable name is free with DD: form
 INPFIL    DD:MYINPUT3        ; variable name is free with DD: form
 OUTFIL    DD:MYOUTPUT1,INCLUDE=ALL
 OUTFIL    DD:MYOUTPUT2,INCLUDE=(1,5,CH,EQ,'SCOTT',AND,16,5,CH,EQ,'TIGER')
 OUTFIL    DD:MYOUTPUT3,INCLUDE=(1,5,CH,NE,'SCOTT',OR,16,5,CH,NE,'TIGER')
 OMIT      DUPRECS

 MYINPUT1=/tmp/myappl/data1 \
 MYINPUT2=/tmp/myappl/data1 \
 MYINPUT3=/tmp/myappl/data1 \
 MYOUTPUT1=/tmp/s1          \
 MYOUTPUT2=/tmp/s2          \
 MYOUTPUT3=/tmp/s3          \
 hxsm700 -vv job12.xsm

No full command-line equivalent for this job, due to DD:varname,INCLUDE=(...) forms.

Job 13 : All In One : Merge + Deduplicate + Skip Header + Selective output with CSV

Parameter File job13.xsm:

#
# Sample CSV demo
#
SORT    VFIELDS=(9,2,C,A,8,30,C,A,10,5,N,A),FIELDSEP=COMMA
;                !                             !
;                !                             +--- Field separator Comma (,)
;                !
;                +-- sort keys #1: Field 9, max len 2, Char, Ascending
;                +----- sort keys #2: Field 8, max len 30, Char, Ascending
;                +----------- sort keys #3: Field 10, max len 5, Numeric, Ascending

RECORD  RECFM=V,LRECL=400
;           !       +--- max record length 400 ;  no NewLine within 400 bytes will raise an error
;           +-- Record Format : Variable

SKIP_HEADERS 1                    ; drop first line from every input file
OMIT DUPLICATE RECORDS            ; remove records with all fields duplicate

INPFIL  clients1.csv              ; input file #1
INPFIL  clients2.csv              ; input file #2, will merge with input file #1

# All :
OUTFIL  DD:ALLCLIENTS

# Only people from New-york state :
OUTFIL  DD:NEWYORKERS,INCLUDE=(9,2,CH,EQ,C'NY')

#  All but  New-yorkers !
OUTFIL  DD:OTHERS,EXCLUDE=(9,2,CH,EQ,C'NY')

 ALLCLIENTS=/myappl/out/clients1.csv \
 NEWYORKERS=/myappl/out/clients1.NY.csv  \
 OTHERS=/myappl/out/tmp/clients1.not_in_NY.csv         \
 hxsm700 -vv job13.xsm

No full command-line equivalent for this job, due to VFIELD and several DD:xxx,INCLUDE=

We have a demo of this job! See the demo

7. Destructive vs non-destructive sort

XSM's default behaviour is to run as a destructive sort: it will not guaranty that original order of records having the same sort key(s) is kept.

Sort programs can produce different and unpredictable results, based on their proper algorithms.

XSM becomes a non-destructive sort, also known as "stable sort" using following option:

Example: input file:

            01234   SMITH     John
            01738   SMITH     Robin
            02284   ALLEN   David
            04264   ALLEN   Bob

Destructive sort (default) result, using sort key = Name :
We get the ALLEN family then the SMITH family, we don't care if firstnames are kept ordered as they where in input file.

            04264   ALLEN   Bob
            02284   ALLEN   David
            01234   SMITH     John
            01738   SMITH     Robin

Non-destructive (or "stable") sort result (sort key = Name) :
We make sure records, once sorted on sort key, are kept ordered as the where in input file.

            02284   ALLEN   David
            04264   ALLEN   Bob
            01234   SMITH     John
            01738   SMITH     Robin

Note: forcing stable sort may decrease performance as the whole record as to be processed, not only the sort keys.
For best performance, it is recommended to add whatever needed supplementary sort keys and avoid forcing stable sort.

8. Performance Issues

See our Performance Table.

The XSM program is a multi-phases sort program: if it cannot sort the whole set of input files internally in main storage, it writes portions of sorted items in temporary files, then merge them onto the final output file.

Performances are tied to:

• the size of the files to be sorted
• the kind of records to be sorted ( Fixed or Variable records)
• the amount of internal memory available
• the quality if Operating System itself
• the number and speed of the physical disk drives available.

File size:

Fixed or Variable records:

Memory available:

Operating System:

Physical Disk drives

9. Running XSM as a User Exit

There are two ways of running XSM as an internal sort, using a User Exit :

1. You provide your own I/O routines in a dynamic library described in the parameter file as indicated below, and XSM will load that library at initialization, then call the I/O routines as needed instead of doing the input/output itself.
2. or, you write your own program that will call the XSM main routine with a parameter string and pointers to your own read/write functions, then compile and link-edit it with the library provided in the XSM package

1. Providing your own dynamic library

   • Write, compile and link-edit your module(s) with the function(s) to read and/or write the INPUT/OUTPUT files, record by record, or line by line:
     • int your_read_routine(char * hxsm_buffer, int hxsm_buffer_max_length)

       Call:

       iteratively until it returns a negative number.

       Shall return:

       the record length if OK,
       or -1 if EOF,
       or -2 in case of an error
       .
     • int your_write_routine(char * hxsm_buffer, int hxsm_buffer_actual_length)

       Call:

       once for each available output record,
       plus once AFTER the last record, with xsm_buffer = NULL and xsm_buffer_actual_length = -1;

       Should return:

       0 or any positive number if OK,
       or a negative number in case of an error.

   • In parmfile, Replace the INPFIL and/or OUTFIL parameters above by:

         INPXIT LIBRARY=libname1,ENTRY=function1
         OUTXIT LIBRARY=libname2,ENTRY=function2
     

     where libname1, libname2 are names of libraries containing functions (may be the same)
     and function1, function2 are respective function names for reading (INPXIT) and writing (OUTXIT)

   On Windows, the libraries are named 'SOMELIB.DLL'.
   On UNIX/Linux, libs are named 'libsomething.a' for static libs or 'libsomething.so' for dynamic libs.

   Example:

   The following module is compiled, then linked to give 'libmysrt.a' (AIX), or 'libmysrt.so' (LINUX), or 'MYSRT.DLL' (Windows):

    #include <stdio.h>
   
    int myread(char * xsm_buf, int xsm_maxl) {
      /* this routine reads on stdin, and arrange the lines to be sorted */
      /* the lines beginning with a '*' are to be dropped                */
      char mybuf[134];
      do    if (gets(mybuf) == NULL) return EOF;
      while (mybuf[0] == '*');
      /* set up the record to be sorted, return its length */
      return sprintf(xsm_buf, "%-5.5s%-20.20s%s", mybuf+20, mybuf,mybuf+25);
    }
   
    int mywrite(char * xsm_buf, int xsm_len)  {
      /* this routine arrange the sorted lines and write them onto stdout */
      if (xsm_len > 0)
        printf("-20.20s%-5.5s%s\n", mybuf+5, mybuf, mybuf+25);
      return 0;
    }
   

   Then the library is moved somewhere in the 'PATH' (Windows), or in the 'LD_LIBRARY_PATH' (UNIX) directories list;

   Finally, the hxsm module is run with the following parameter file:

    SORT      FIELDS=(25,5,B,D,1,20,B,A)
    RECORD    RECFM=V,LRECL=132
    INPXIT    LIBRARY=mysrt,ENTRY=myread
    OUTXIT    LIBRARY=mysrt,ENTRY=mywrite
   

2. Using the XSM routines

   The XSM software includes a library with a public routine that may be called from your own programs written in any compiled language supporting link-edit, such as C, C++, C#, VB, ...:

   the hxsm_begin routine

   Synopsis: int hxsm_begin(parms_string, my_read_function, my_write_function)

   where:

   parm_string is either a parameter file-name or the traditional parameters, options, and flag string of the hxsm command-line.

   my_read_function is a pointer to your own input routine with the following syntax:

   int myread(char * buffer, int max_length)

   and which, when called, should either provide the next record to be sorted end its length, or return max_length = -1 for the end of the input stream (EOF).

   my_write_function is a pointer to your own output routine with the following syntax:

   int mywrite(char * buffer, int rec_length)

   and which, when called, will receive either the next sorted record and its length, or a NULL buffer and a length = -1 (EOF).

   returns: 0 if OK, a negative number if a parameter is not correct.

   Example:

   The following program will prompt for a name and an amount, until the user hits the EOF (^Z or ^D) key, will sort and display all the input lines in decreasing amount order, with a total as the last display.

   It is compiled and linked against the hxsm library:

    #include <stdio.h>
   
    double atof(), total = 0.0;
   
    static int myread(char * buf, int maxlen) {
      char work_area_1[133], work_area_2[133];
      double amount;
      /* prompt for a name and an amount, returns -1 if EOF */
      printf("Name   :" ); if (gets(work_area_1) == NULL) return -1;
      printf("Amount :" ); if (gets(work_area_2) == NULL) return -1;
      amount = atof(work_area_2);
      return sprintf(buf, "%9.2f %-30.30s", amount,  work_area_1);
    }
   
    static int mywrite(char * buf, int len) {
      if (len > 0)
          printf("%-30.30s %-12.12s\n", buf + 13, buf);
      return len; /* will be ignored by hxsm */
    }
   
    main(int argc, char **argv) {
      int rc = hxsm_begin("MYPRM.XSM", myread, mywrite);
      if (rc == 0)
        printf("%-30.30s %9.2f\n", "*** TOTAL ***", total);
      else
        printf("Failed, rc %d\n", rc);
      return rc;
   }
   

   The program uses following parameter file 'MYPRM.XSM':

    SORT      FIELDS=(1,12,B,D)
    RECORD    RECFM=V,LRECL=132
   

   It can also be written with the following hxsm_begin statement:

     int rc = hxsm_begin("-k1,12,d", myread, mywrite);
   

   and then run straight without any parameter file.