uvcopy1.doc - introduction, functions,& instruction summary

uvcopy1.doc - Contents

A1. Documentation: uvcopy1(functions), uvcopy2(options), uvcopy3(instructions)
A2.   uvcopy4,5,6,7(sample jobs), UVjobs1(best samples), uvtrain(training guide)
A3.   uvcopy is easy to learn & extremely powerful
A4.   How does uvcopy find its parameter files ?
A5.   uvcopy & other utilities (uvcp, uvsort, etc)
A6.   the Vancouver Utilities - Summary & History
B1. UVCOPY Program Description
B2.   UVCOPY Program Feature Summary
B3.   Debugging uvcopy jobs & Interrupt Processing
C1. Introductory examples 1,2,3
C4.   uvcopy 'skeleton' job to copy/rename/modify as required
D1. Functions & Instructions (differences)
E0. Group 1 Functions (prior to File declarations)
E1. 'prm' - declare parameter file name (PFPATH)
E2. 'opr' - operator message
E3. 'rop' - run option declaration
E4. 'uop' - user option declaration
E5. 'was' - work area size assignment
E6. 'arg' - command line arguments
F0. FILE Function Group (fil,typ,rcs,isk)
F1. 'fil' - file declaration sets & examples
F2. 'fil' - file-name declaration
F3. 'typ' - file-type declaration
F4.  'options' - file-type options a -->
F9.  'options' - file-type options --> z
G1. 'rcs' - record-size declaration
G2. 'isk' - ISAM file key declaration
G3. 'fil' - 4 ways to specify file-names
G4.  'typ=RSV' Record Sequential Variable files
- compatible with Micro Focus COBOL IDXFORMAT3 files
G5. typ=STL - STandard Language file system, used by AIX COBOL
STLs - STL Sequential files (input & output)
STLi - STL Indexed files (input only)
STLr - STL Relative record files (input only)
H0. Group 1 Functions (prior to File declarations)
H1. 'lod' - load a data table into a work area
H2. '@run' - end functions / begin instructions
H3. '@pf2' - declare 2nd file of instructions to load at run-time
I1. Instruction Formats
J1. $symbols - equating to operand area.displacement(length)

Goto:   Begin this document End this document UVSI Home-Page

uvcopy1.doc - Contents (continued)

K0. Instruction Summary by Functional Groups
K1. _________logical: mvc,mvf,mvr,mvp,cat,clr,edt,anc,orc,xor
K2. ______arithmetic: mvn,add,sub,mpy,div,pac,unp,xft
K3. __comp/test&skip: cmc,cmn,skp,nop,tst,tsb,mwb
K4. __sequential I/O: opn,cls,get,put,rel,rtb,wtb
K5. _____indexed I/O: set,red,wrt,upd,del,lck,ulk
K6. _message&control: msg,can,eoj,tim,wat,bal,ret,bcr
K7. _____translation: tra,tre,trl,tru,trt,hxc,chx,vhx
K8. ____scan&replace: scn,rep,mvu,sct,rpt,sts,rts
K9. __squeeze-insert: sqz,sqf,jus,cnt,ins
K10. _____conversion: fix,var,dlm,und,swp,rfm,dat
K11. ________special: sys,lok,pop,fxt,env,evt
K12. ___________sort: sxo,sxp,sxs,sxg,sxc,srt
K13. __________table: tbl,tbf,tbh,tbp,tbd

Goto:   Begin this document End this document UVSI Home-Page

A1. uvcopy Documentation - uvcopy1,2,3,4,5,6,7.doc

uvcopy1.doc - FUNCTIONS

Functions are declarations (not executed as are instructions). Functions are processed once only at setup time. '@run' separates Functions from Instructions.

            initial:  prm,opr,rop,uop,was
          arguments:  arg1,arg2,...,arg9
   file declaration:  fil__,typ,rcs,isk
  special functions:  lod
 begin instructions:  @run

uvcopy2.doc - Work areas, $symbols, options, etc

 Work Areas - 26 work areas (a-z)
 $symbols   - for registers, counters, system values (date,time,filenames,etc)
 Options    - user options, run options, file type options
 Index Registers - explanations & examples
 Debugging  - step thru program, display work areas, breakpoints, etc

uvcopy3.doc (this doc) - INSTRUCTIONS

Instructions follow the '@run' function & are stored in memory at 'setup time'. Instructions are executed at 'run time' (after validation at setup time). Instructions are usually executed repeatedly (eg: for each record in a file)

  1. logical: mvc,mvf,mvr,mvp,cat,clr,edt,anc,orc,xor,shf
  2. arithmetic: mvn,add,sub,mpy,div,pac,unp,xft
  3. comp/test/skip: cmc,cmn,skp,nop,tst,tsb,mwb
  4. sequential I/O: opn,cls,get,put,rel,rtb,wtb
  5. Indexed I/O: set,red,wrt,upd,del,lck,ulk
  6. message&control: msg,can,eoj,tim,wat,bal,ret,bcr
  7. translation: tra,tre,trl,tru,trt,hxc,chx,vhx
  8. scan&replace: scn,rep,mvu,sct,rpt,sts,rts
  9. squeeze-insert: sqz,sqf,jus,cnt,ins,ctr
  10. conversion: fix,var,dlm,und,swp,dat,rfm
  11. special: sys,lok,pop,fxt,env,evt,vnf,xxa,xxb,xxc
  12. sort: sxo,sxp,sxs,sxg,sxc,srt
  13. table: tbl,tbf,tbh,tbp,tbd

Goto:   Begin this document End this document UVSI Home-Page

A2. uvcopy Introduction & Overview

uvcopy examples/test/demo jobs

uvcopy4.doc
  • record reformatting, using builtin sort, table lookups
uvcopy5.doc
  • converting delimited files to fixed & vice-versa
  • splitting files, chaining to Indexed files, etc
uvcopy6.doc
  • test/demo jobs for Indexed files compatible with Micro Focus COBOL
  • IDXFORMAT1(fixed), IDXFORMAT3(variable), IDXFORMAT8(var > 2 gig)
uvcopy7.doc
  • text manipulation utility jobs (mass search/replace)
  • demo mass changes to scripts & programs
UVjobs1.doc
  • uvcopy demo jobs with supplied test data files
  • translates, convert tabs, print calendars, table summaries, etc
  • run these jobs & compared your results to expected results
  • might be a good place to start learning uvcopy.
uvtrain.doc
  • Training Guide for Vancouver Utilities
    (uvlist, uvhd, uvcp, uvsort,& uvcopy)

what is 'uvcopy' ?

uvcopy is a 'general purpose' (can do anything) data file manipulation utility. It gives you the power of assembler without the complexity. The uvcopy interpreter interprets/executes a source file of instructions. For example to execute 1 of the supplied uvcopy demo jobs:


 uvcopy calendar1  <-- print a calendar (with Julian dates) for the current month
 ================      or any range of months by options entered at the prompt

There are over 500 pre-programmed 'uvcopy jobs' supplied with the Vancouver Utility package. many of these are used in mainframe conversions. For example the COBOL converter is a uvcopy job (but the JCL converter is a C program).

Many supplied uvcopy jobs should be useful to any Unix/Linux site and especially for sites running applications that have been converted from a mainframe. For example 'cobmap1' will create a record layout from a COBOL copybook, and 'xcobcopy2' will create a COBOL copybook cross-reference.

Goto:   Begin this document End this document UVSI Home-Page

A3. uvcopy Introduction & Overview

Why do we need uvcopy ?

The Vancouver Utiltiies are primarily used to convert & execute mainframe applications (JCL,COBOL,DATA) on Unix/Linux systems. 'uvsort' replaces the mainframe 'SORT'. 'uvcopy' can be used to replace various mainframe utilties such as IDCAMS, IEBGENER, DITTO, FILEAID, EASYTRIEVE, QUIKJOB, etc.

'uvcopy' is essential to running mainframe applications on Unix/Linux systems, because it can do many things not possible with the standard unix/linux utilities such as: processing 'packed decimal' fields, handling 'Indexed files' (compatible with Micro Focus COBOL),& field addressing by column# (common in mainframe utilities, but not in unix utilities).

uvcopy is easy to learn

The interpretive nature of uvcopy makes it easy to learn & to use. If you have a mainframe backgound, you will probably be familiar with the uvcopy instruction formats since they are patterned after the IBM 360 assembler.

uvcopy is powerful

uvcopy has over 90 instructions and about half of these are pwerful subfunctions. For example 'tbl' will build a summary table in memory based on any argument & up to 6 accumulators. It creates a new entry for new arguments & adds to existing entries on matching arguments. The table is usualy dumped to a report file at EOF by the 'tbp' instruction.

As a 2nd example, the 'rpt' instruction will perform search/replace on any area (the current data record probably) using a table of search/replace/qualifier patterns that may have been loaded from a file via the 'lod' instruction.

Goto:   Begin this document End this document UVSI Home-Page

A4. uvcopy Introduction & Overview

how does uvcopy find its parameter files ?

uvcopy finds its instruction files ('parameter files' or 'uvcopy jobs') via an environmental variable 'PFPATH' in the profile (similar to 'PATH').


 export PFPATH=$HOME/pf:$UV/pf/adm:$UV/pf/demo:$UV/pf/util:$UV/pf/IBM
 ====================================================================

Using the above export, uvcopy will look first in the 'pf' subdir in your homedir, and then in the pf/subdirs supplied with Vancouver Utilities.

This means that if you wanted to modify 1 of the supplied uvcopy jobs, you could copy it to your $HOME/pf, modify as you desire, and the uvcopy interpreter will find your modified version first.


 cp /home/uvadm/pf/demo/calendar1 pf  <-- copy supplied job to your homedir/pf
 ===================================

 vi pf/calendar1       <-- modify supplied job as you desire
 ===============

 uvcopy calendar1      <-- uvcopy will now find your modified version first
 ================

 uvcopy /home/uvadm/pf/demo/calendar1  <-- could execute original like this
 ====================================

 uvcopy pf/calendar1   <-- could execute your modiifed job like this
 ===================       (but no need if profile export PFPATH as above)

Goto:   Begin this document End this document UVSI Home-Page

A5. the Vancouver Utilities - Summary & History

uvcopy & other utilities

'uvcopy' is a general purpose parameter driven data manipulation utility. It is an 'interpreter' for instructions in a separate parameter file. It is the most powerful program in the Vancouver Utilities package and is the basis for many pre-programmed jobs documented separately (SCANjobs, REPjobs, TABLEjobs, LISTjobs, CMPjobs, etc).

uvcopy is an essential part of the mainframe conversions because it can do many things not possible with the standard unix/linux utilities (such as processing packed decimal fields & handling Indexed files compatible with Micro Focus COBOL).

This is the program reference manual, & is not necessarily the best starting point for learning the Vancouver Utilities. Uvcopy is by far the most powerful and therefore has a longer learning curve due to the many instructions which are coded in a parameter file.

The other utilities such as uvcp & uvsort are easier to learn since they have a much smaller instruction set and can be entirely driven from the command line. Please see the documentation which includes many examples of record selections and reformatting that can be specified on 1 line.

The pre-programmed jobs will also help you to learn uvcopy. Start with UVjobs1.htm. The pre-programmed jobs are presented in a tutorial manner, starting with simple jobs & progressing to more complex jobs.

The pre-programmed jobs can be run immediately with the test data supplied, and when you find a job that you would like to run with one of your own files, you can simply enter your filename at the prompt instead of entering null to accept the default test file.

When you find 1 of these pre-programmed jobs that does not quite do what you want, then examine the job instructions which are listed following each job description and operating instructions. Since the instructions are interpretive, you need only the editor to modify them and rerun the job. When the changes are not immediately apparent, that is the time to research the reference manuals to see how you can change the instructions to obtain the results you desire.

In this manner, you will soon progress to writing your own jobs to solve complex problems that previously could not have been solved without a professional programmer writing programs in COBOL or C.

Goto:   Begin this document End this document UVSI Home-Page

A6. the Vancouver Utilities - Summary & History

Vancouver Utilities - Summary

The primary intention of this package is to provide a powerful general purpose parameter-driven data manipulation facility, that can be used for file conversions, file maintenance,& production data processing. The utility programs are written in C for UNIX & MS-DOS and include: uvcopy, uvsort, uvlist, uvhd, uvcp,& jclunix.

Uvcopy is the most powerful utility (parameter file interpreter) & over 500 parameter files (pre-programmed jobs) are provided to perform functions such as: scan/replace, translation, record selection/modification, creating import/export file formats, converting word-processing files, label printing, text re-pagination, etc. The scan/replace jobs can scan an entire directory of files for any 1 pattern or for any pattern in a table of patterns prepared with the editor.

Uvsort includes functionality not available in the UNIX sort such as indexed file access and packed decimal keys. ISAM file I/O is provided for Micro Focus COBOL (MBP-COBOL & SCO-ISAM now obsolete).

Several conversion aids are provided for mainframe customers who are migrating to UNIX. Jclunix will convert mainframe JCL to UNIX scripts. cnvMF5 will convert mainframe cobol to Microfocus cobol. Uvsort is provided as a replacement for the mainframe sort (since the UNIX system sort is unsatisfactory). Uvcp is provided as a replacement for the mainframe 'DATA' & 'MILOAD' utilities.

History of Vancouver Utilities

The Vancouver Utilities were originally developed for the Unisys System 80 mainframe computers during the many years I worked for Unisys. In 1993, after many years with Unisys and 2 years with Allinson-Ross, I (Owen Townsend) incorporated UV Software Inc to develop and market software for UNIX systems with the initial emphasis on assisting mainframe customers to convert to UNIX.

The first version was installed at the first customer site in May 1993 & as of January 2002 the package is installed at over 50 sites. The package is being continually enhanced (often due to customer feedback & suggestions) and annual updates are available.

Goto:   Begin this document End this document UVSI Home-Page

B1. uvcopy - file copy & data manipulation utility program

uvcopy program description

Uvcopy is a file copy & data manipulation utility written in 'C' for use on any system that supports the C language such as UNIX, MS-DOS,& OS2.

Uvcopy evolved from the UVCOPY program for UNISYS OS/3 mainframes and one of the initial motivations was to assist mainframe users to convert to UNIX systems. Uvcopy is ideally suited to perform the translations & data conversions required or desired (EBCDIC to ASCII, UPPER to lower, packed to binary).

Uvcopy is intended as a general purpose data manipulation utility which can be used to reformat files, modify records, and perform almost any imaginable data data conversion that may be desired. especially useful when transferring files to new machines or converting record layouts to fit the requirements of new application packages.

The program provides over 90 instructions to perform record selection, reformatting, translation, and field conversion such as packed to zoned or to binary.

The flexible instruction set can respond to the unpredictable problems that can occur during conversions or at anytime in data processing. Uvcopy greatly reduces the necessity to write those 1 shot programs that are otherwise required to solve unanticipated problems.

Uvcopy is am interpretive utility which is driven by a parameter file which may contain a number of very powerful instructions limited only by available memory. The command line must specify the name of the parameter file & may also override filenames & options in the param file.

Also note there is another somewhat similar utility called 'uvcp', which does not need a separate 'parameter file', since its instructions can be specified on the command line. Use uvcp when you do not need the full power of the uvcopy utility. uvcp is more than adequate as a replacement for the some mainframe DATA utilities which have limited record selection & record reformatting capabilities.

uxcopy alternate version of uvcopy

uxcopy is an alternate version of uvcopy to support Micro Focus COBOL IDXFORMAT3 Record Sequential Variable & Indexed Sequential Variable length files. See file typ=IDXf3 & typ=IDXf8 on page 'F3' in this uvcopy1.doc.

uxcopy must be compiled with Micro Focus COBOL server express v2.2 or higher. It is therefor only applicable to Micro Focus COBOL customers. See compile instructions on page D1 of install.htm#D1.

Goto:   Begin this document End this document UVSI Home-Page

B2. UVCOPY Feature Summary

Goto:   Begin this document End this document UVSI Home-Page

B3. UVCOPY Feature Summary

uvcopy DEBUGGER

You can turn on the uvcopy debugger via run option 'd', for example:


 uvcopy jobxxx,rop=d          <-- run uvcopy with debugger enabled
 ===================

In debug mode uvcopy displays each instruction before execution. Press enter to execute each instruction or 'g' to go (run to end of job or next breakpoint). Rather than the 'b'reakpoint, I think you will find the 't'ag breakpoint more useful ('t' runs until it finds the specified tag (instruction label). You can display I/O & work areas. See complete debugger documentation at the end of uvcopy2.doc, but a few examples follow here:

 -->         <-- null entry to execute next instruction

--> d a0 <-- display area 'a' from 1st byte (60 bytes length by default)

 --> x x200  <-- hex display area 'x' from byte 200 (60 bytes by default)

--> t man20 <-- set breakpoint at tag man20 (instruction label)

 --> t       <-- continue to same tag as previously stored

INTERRUPT processing

You may press the 'interrupt' key while copying files. Interrupt causes a display of current input/output record counts & prompts you for a response. Enter 'q' to close files & end the program, or null to continue.

Interupts are disabled by default since they can sometimes cause problems (such as orphan processes) when uvcopy is executed from a script.

You can enable interupts via run option 'e1'. You might do this when you run a uvcopy job from the command line, for example:


 uvcopy jobxxx,rop=e1         <-- run uvcopy job with interupts enabled
 ====================

Goto:   Begin this document End this document UVSI Home-Page

C1. uvcopy INTRODUCTORY EXAMPLE #1

given
  • a customer master file of 256 byte records
  • ISAM file keyed on cust# & name
required
  • copy the file to an unkeyed sequential file for backup
  • 256 byte records with a line feed in 256 in case it is
    desired to examine the file with an editor
solution
  • first use the editor to prepare the parameter file
    shown below & then execute the 'uvcopy' program using the
    command line shown folowing the param file list

custbkup - uvcopy job sample #1

 # custbkup - parameter file for uvcopy to backup customer master file
 #          - custmas is ISAM 256 byte records keyed on customer#
 #            1st 6 bytes & on name bytes 11-25
 #          - custbak will be sequential file 256 bytes with LF in 256
 fili1=custmas1,typ=ISF,rcs=256,isk1=0(6),isk2=10(25)
 filo1=custbak,typ=LST,rcs=256
 @run
        opn   all                  # open files
 loop   get   fili1,a0(256)        # get each input rec into area 'a'
        skp>  eof                  # condition code set > at end of file
        mvc   b0(256),a0           # move input area 'a' to output area 'b'
 #      ---   ----------             any record modification would go here
 #      ---   ----------             (see example #2)
        put   filo1,b0(256)        # write out the record from area 'b'
        skp   loop                 # repeat the loop until end of file
 eof    cls   all                  # close the files
        eoj                        # end the job

 uvcopy custbkup          - execute uvcopy to interpret prmfile custbkup
 ===============
Notes
  • file type 'ISF' means Indexed Sequential Fixed records
    or ISam File - DISAM (compatible with Microfocus)
  • file type 'LST' means Line Sequential records Terminated
    by a line feed in the last byte if Unix
    or by a CR/LF in the last 2 bytes if MS-DOS
  • record byte addresses are always zero relative & data movement
    is always from op2 to op1
  • uvcopy provides 26 record/work areas identified by prefix a-z
  • the intended areas should be specified on the 'rcs' parameter
    as well as the get/put to ensure a large enough area is allocated
    & also to invoke bounds checking on data moves,etc

Goto:   Begin this document End this document UVSI Home-Page

C2. uvcopy INTRODUCTORY EXAMPLE #2

given
  • same customer master file as for example #2
    which contains the following pertinent fields:
    001-006 - customer# (key#1)
    011-035 - customer name (key#2)
    121-180 - current years sales jan-dec
    12 x 5 byte packed fields
    181-240 - last years sales jan-dec (12 x 5)
required
  • reload the customer master file (backed up in example 1)
    while performing year end modifications & selections:
  • move this year sales fields to last year sales fields
  • drop any records that have no sales in the year ended
  • zero out all fields for the new current year
solution
  • prepare the parameter file 'custyear' shown below & then
    execute uvcopy using the command line shown below that

custyear - uvcopy job sample #2

 # custyear - parameter file for uvcopy to restore customer master file
 #            with year-end record modifications & selections
 fil11=custbak,typ=RST,rcs=256
 filo1=custmas1,typ=ISF,rcs=256,isk1=0(6),isk2=10(25)
 @run
        opn   all
 loop   get   fili1,a0(256)
        skp>  eof
        mvc   b0(256),a0
        xft   c0(4b),a120(5p),12   # crossfoot this yr sales
        skp=  loop                 # cc set = if zero, bypass record
        mvc   b180(60),a120        # move this year sales to last year
        mvnx12 b120(5p),0          # zero out all this yr fields
        put   filo1,b0(256)
        skp   loop
 eof    cls   all
        eoj

 uvcopy custyear          - execute uvcopy to interpret prmfile custyear
 ===============
Notes
  • the 'xft' instruction crossfoots the 12 5 byte packed fields from
    121-160 of the input area 'a' into the work area 'c' 1st 4 bytes
    ('4b' means binary integer, but could have been packed or zoned)
  • the 'xft' instruction also sets the condition code '=' if the
    result is zero, & the 'skp= loop' will drop these records
  • the 'x12' of the 'mvnx12' instruction specifies the repeat option
    to repeat the move numeric 12 times to zero all 12 fields 121-180

Goto:   Begin this document End this document UVSI Home-Page

C3. uvcopy INTRODUCTORY EXAMPLE #3

given
  • a COBOL program from an EBCDIC mainframe
required
  • convert for UNIX COBOL compilers (Micro Focus, Open COBOL)
  • translate EBCDIC to ASCII
  • translate UPPER case to lower case
  • clear cols 1-6 & 73-80
  • replace single quotes with double quotes
  • replace 'UNISYS-OS3' with 'MBP-COBOL' or whatever
    (could add many more 'rep's depending on site preferences)
Note
  • we will assume the input program is in file 'cobolEBC' & we will
    write the output to file 'cobolASC'
  • please see the 'cnvcobp' parameter file & the 'cnvcobs' script
    presented near the end of this uvcopy documentation
  • cnvcobp & cnvcobs are more comprehensive & have been used to
    convert entire directories of cobol programs from mainframe to UNIX
  • cnvcobp also inserts the cobol code required for the 'initftab'
    subroutine which restores the logical/physical filename
    relationships used on mainframes
 # cnvcob1 - convert a COBOL program from an EBCDIC mainframe to UNIX ASCII
 fili1=cobolEBC,rcs=80,typ=LST
 filo1=cobolASC,rcs=80,typ=LSTt
 @run
       opn   all
 loop  get   fili1,a0(80)          # get record into area 'r'
       skp>  eof
       mvc   b0(80),a0             # move record to w/a w
 #     tra   b0(80)                # translate to ASCII
 #note - the translate to ASCII is commented out since it has probably
 #  already been done when loaded on the UNIX machine (TIP/ix LIBS)
       trlq3 b0(80)                # translate to lower case
 #                                   - except in quotes (option q3)
       clr   b0(6),c' '            # blank cols 1-6 & 73-80
       clr   b72(8),c' '
       cmc   b6(1),c'*'            # cobol comment line (* col 7) ?
       skp=  put                   # yes - no further conversion required
       rep   b7(65),x'27',x'22'    # replace single quotes w double quotes
       rep   b7(65),'UNISYS-OS3','MBP-COBOL'
 #     ---   - could add more 'rep's here for unique site requirements
       put   filo1,b0(80)          # write out the current record
       skp   loop                  # return to get next rec until EOF
 eof   cls   all
       eoj

 uvcopy cnvcob1           - execute uvcopy to interpret prmfile cnvcob1
 ==============

Goto:   Begin this document End this document UVSI Home-Page

C4. uvcopy skeleton - template job to copy, rename,& modify as required

 # skeleton - uvcopy template job, copy/rename/modify & modify as required'
 #          - be sure to update these lines with new name & job description'
 opr='$jobname - uvcopy skeleton job, copy/rename & modify as required'
 fili1=?input,typ=LST,rcs=256          # code filenames or leave ? for prompt
 filo1=?$jobname.tmp,typ=LSTt,rcs=256  #
 @run
       opn   all                    open files
 # begin loop to get & put records until EOF
 loop  get   fili1,a0               get record into area 'a'
       skp>  eof                    (condition code set > at EOF)
 #-----------------------------
       mvc   b0(256),a0             move input record to output area 'b'
 #     ---   -----,-----            ** add your instructions here **
 #-----------------------------
       put   filo1,b0               write record to output file
       skp   loop                   return to get next record
 #
 eof   cls   all                    close files
       eoj                          end job

The 'skeleton' job shown above is provided for you as a starting point intended for you to copy, rename,& modify as required.

The following example suggests how you would use the uvcopy skeleton job, if you wished to create a new uvcopy job called 'fix1'.


      mkdir pf2                 - make a sub-directory for your jobs
      =========                   (1st time only, name as you wish)

      cp pf/skeleton pf2/fix1   - copy skeleton to your sub-directory
      =======================     renaming as you wish (fix1 in this case)

      vi pf2/fix1               - modify the job as required
      ===========               - inserting your instructions
                                - modifying file names, types,& record sizes
                                - don't forget to change comment lines
                                  to new name & job description

      uvcopy pf2/fix1           - execute uvcopy to interpret your prmfile
      ===============
       - - if errors - -        - correct errors & rerun

Please see the notes on the next page: "customizing the skeleton job to solve your current problem"

Goto:   Begin this document End this document UVSI Home-Page

C5. Customizing the uvcopy 'skeleton' job to solve your current problem

When you want to make a new job, the following steps are recommended:

 1  - Copy the 'skeleton' job to whatever name you decide to assign to
      your new job.
    - I strongly recommend you keep your prmfiles in a sub-directory from
      your home directory similar to the 'pf' directory which is a
      sub-directory from the 'uv' home directory.
 2  - Edit your new job.
    - Be sure to change the jobname on line 1; you don't need to change on
      the 'opr' statement since it is coded as '$jobname'.
    - Be sure to fill in your job description on line 1
      & on the 'opr' statement.
 3  - Modify the input/output file declarations if required
    - Note that the skeleton job file declarations are as follows:
      fili1=?input,typ=?LST,rcs=256
      filo1=?$jobname.tmp,typ=?LSTt,rcs=256
 3a - You might as well hard-code your specific filenames, replacing
      '?input & ?$jobname.tmp'. You could leave the '?' prefix if you
      anticipate using the job with various files. The '?' causes an
      an operator prompt for a new filename (null reply for default).
 3b - The file types default to 'LST' (variable-length LF Terminated).
    - Change to 'RST' if your records are fixed-length, LF Terminated,
      or to 'RSF' if your records are fixed-length, without LineFeeds.
 3c - The record size defaults to 256, which is OK if your file types
      are 'LST' & do not exceed 256.
    - For fixed-length records, you must change to the correct values.
      (see complete details re 'typ' & 'rcs' in uvcopy1.doc)
 4  - Insert your instructions as required into the get/put loop:
      #-----------------------------
            mvc   b0(256),a0             move record to output area 'b'
      #     ---   -----,-----          *** add your instructions here ***
      #-----------------------------
 5  - Debug your job. You probably wont get it right 1st time, but the
      diagnostics usually pinpoint your clerical errors. The logic is
      up to you, but the interpretive nature of uvcopy allows you to
      change & rerun very quickly.

Goto:   Begin this document End this document UVSI Home-Page

C6. Customizing the uvcopy 'skeleton' job - EXAMPLE

 # skeleton - uvcopy template job, copy/rename/modify & modify as required'
 #          - be sure to update these lines with new name & job description'
 opr='$jobname - uvcopy skeleton job, copy/rename & modify as required'
 fili1=?input,typ=LST,rcs=256          # code filenames or leave ? for prompt
 filo1=?$jobname.tmp,typ=LSTt,rcs=256  #
 @run
       opn   all                    open files
 # begin loop to get & put records until EOF
 loop  get   fili1,a0               get record into area 'a'
       skp>  eof                    (condition code set > at EOF)
 #-----------------------------
       mvc   b0(256),a0             move input record to output area 'b'
 #     ---   -----,-----            ** add your instructions here **
 #-----------------------------
       put   filo1,b0               write record to output file
       skp   loop                   return to get next record
 #
 eof   cls   all                    close files
       eoj                          end job

EXAMPLE - modifying 'skeleton' to solve a problem

given
  • COBOL programs originally from a mainframe that have program-id
    duplicated in cols 73-80 of every source line.
    (or worse - in some but not all lines)
required
  • Blank out columns 73-80.
  • This will clean up the source code & also save disc space since
    the 't' option of 'LSTt' truncates trailing blanks.
    (blank lines become 2 bytes vs 81 bytes)
solution
  • Add the following instruction to the skeleton job.
    (you would copy & rename as explained 2 pages previously)
       #-----------------------------
             mvc   b0(256),a0          move input record to output area 'b'
       #     ---   -----,-----         ** add your instructions here **
             mvc   b72(8),' '             clear cols 73-80          <------
       #-----------------------------
Note
  • if you also wanted to re-sequence# in columns# 1-6, you could
    add the following 2 instructions:
             add   $ca1,1               increment a line counter
             mvn   b0(6),$ca1           move the sequence# into cols 1-6
Note
  • you would use the 'uvcopyx' script, if you wanted to run a uvcopy
    job such as this, for all files in a directory.

Goto:   Begin this document End this document UVSI Home-Page

D1. uvcopy FUNCTIONS and INSTRUCTIONS

functions

            initial:  prm,opr,rop,uop,was
          arguments:  arg1, arg2, ... arg9
   file declaration:  fil__,typ,rcs,isk
  special functions: lod
 begin instructions: @run

Instructions

  1. logical: mvc,mvf,mvr,mvp,cat,clr,edt,anc,orc,xor
  2. arithmetic: mvn,add,sub,mpy,div,pac,unp,xft
  3. comp/test/skip: cmc,cmn,skp,nop,tst,tsb,mwb
  4. sequential I/O: opn,cls,get,put,rel,rtb,wtb
  5. Indexed I/O: set,red,wrt,upd,del,lck,ulk
  6. message&control: msg,can,eoj,tim,wat,bal,ret,bcr
  7. translation: tra,tre,trl,tru,trt,hxc,chx,vhx
  8. scan&replace: scn,rep,mvu,sct,rpt,sts,rts
  9. squeeze-insert: sqz,sqf,jus,cnt,ins
  10. conversion: fix,var,dlm,und,swp,dat,rfm
  11. special: sys,lok,pop,fxt,env,evt
  12. sort: sxo,sxp,sxs,sxg,sxc,srt
  13. table: tbl,tbf,tbh,tbp,tbd
FUNCTIONS
  • declarations (not executed as are instructions)
  • processed at setup time (when parameters read & validated)
  • processed once only at setup time
  • ended by '@run'
INSTRUCTIONS
  • must follow the '@run' function
  • stored in memory at setup time
  • executed at run time (after all instructions stored & validated)
  • usually executed repeatedly (eg: for each record in a file)

Goto:   Begin this document End this document UVSI Home-Page

E0. uvcopy FUNCTION SUMMARY

Group1 Functions (prior to FILE functions)

 prm=paramfile              - declare name of the parameter file which
                              contains most functions & all instructions
                            - may omit 'prm=' when prmfile name is the only
                              argument on the command line
 arg1=aaa,arg2=bbb,...,arg9 - command line arguments, to introduce misc data
                              into areas accessible by instructions
                              ($arg1,$arg2,etc,$arg9)
 opr='--- oprtr msg ---'    - display operator messages
                            - similar to 'msg' but different because 'opr'
                              is a function (not an instruction) & is
                              executed only once at program initialization
                              (vs possibly being executed many times in a loop)
 rop=abc...xyz              - declare misc run options
                              (meanings preassigned by uvcopy)
 uop=abc...xyz              - declare user run options
                              (assigned by the prmfile writer)
 was=a500b1000...q8000      - declare work area sizes
                            - see work areas documented in uvcopy2.doc

FILE Declaration Functions

 fili1=infilename                - declare input filename
 typ=RSF/RST/LST/ISF/RSV/IDX/STL - declare file type
 rcs=9999                        - declare record size
 iskx=start(length)              - declare indexed file keys
 filo1=outfilename               - declare output filename
 ,typ,rcs,isk                    - same as for input file
 filr1=ranfilename               - declare random filename
 ,typ,rcs,isk                    - same as for input file

Group3 Functions (after Files, excepting Instructions)

 lod=m0(20)                 - load a table in a work area with the
 ..........                   data lines following
 ~~                           until '~~' tildes in col 1 & 2
 @run                       - declares end of functions
      ---- ---,---            & beginning of instructions which follow
 @pf2=paramfile2            - declare 2nd file of instructions to be
                              loaded at execution time

Goto:   Begin this document End this document UVSI Home-Page

E1. PFPATH search path for parameter files

PFPATH is an environmental variable that uvcopy (& uvqrpg) use to find their parameter files. The uvcopy parameter files (also called jobs or programs) are by convention & tradition stored in sub-directories named 'pf'. There may be several of these defined by PFPATH in your .profile, for example:


 export PFPATH=$HOME/pf:./pf:/home/uvadm/pf
 ==========================================

Note that '/home/uvadm/pf' should come last, in case you assign a jobname that duplicates 1 of the demo jobs supplied with the Vancouver Utilities. PFPATH is similar to the unix PATH for programs & scripts - the sub-directories are searched in the sequence defined.

Of course you may also specify a full path or relative path (at least 1 '/') which will be always be searched first & PFPATH segments searched last.


 uvcopy /u1/apps/libs/pubs/pf/uvjobxx   <-- example of full path name
 ====================================

 uvcopy mypf/uvjobxx                    <-- relative path name
 ===================

 uvcopy uvjobxx        <-- will be prefixed with each segment of PFPATH
 ==============            for multiple searches

 uvcopy prm=uvjobxx    <-- may use keyword 'prm' (but now considered obsolete)
 ==================

PFPATH new as of March 2003

Prior to March 2003, uvcopy searched 4 separate paths (PFPATH1,2,3,4) to find its parameter files (vs the current 1 ':' delimited PFPATH). For example:


 export PFPATH1=/home/uvadm/pf   <-- OBSOLETE, replaced by ':' delimited PFPATH
 =============================

If you are upgrading from an older version of Vancouver Utilities, you must change the separate PFPATH1,2,3,4 to the new (& improved) ':' delimited PFPATH.

Goto:   Begin this document End this document UVSI Home-Page

E2. 'opr' - operator messages

examples

opr='$jobname
  • print laser labels 30 labels per page'
opr='
  • user option p is pages of labels desired (p1 default)'
Notes
  • I recommend that your 1st function would be similar to the above
  • $jobname will be replaced by the parameter filename
    & the following text informs the operator what the job does

Goto:   Begin this document End this document UVSI Home-Page

E3. 'rop' - declare 'RUN' OPTIONS

run options are used to declare options for the entire run

 rop=d                  - example
                        - sets debug mode
       ***********************************************************
       run options NOT documented here - SEE SECTION uvcopy2.htm
       ***********************************************************

E4. 'uop' - declare 'USER' run OPTIONS

user options are assigned by the uvcopy job author & not interpreted by uvcopy except for options q & i

   uop=q1p1s1       - example
       ***********************************************************
       run options NOT documented here - SEE SECTION uvcopy2.htm
       ***********************************************************

Goto:   Begin this document End this document UVSI Home-Page

E5. 'was' - function to modify work area size defaults

Only required when the default size of 1 or more of the work areas a-w is insufficient for your current application.

See the work area descriptions & defaults described in uvcopy2.doc.

   was=a999b999c999...r9999      - format
   was=a8000b16000               - set the size of area 'a' to 8000 bytes
                                   & the size of area 'b' to 16000 bytes
       ***********************************************************
       see details re 'work areas' in next section --> uvcopy2.doc
       ***********************************************************

Goto:   Begin this document End this document UVSI Home-Page

E6. 'arg' - command line arguments - arg1=aa,arg2=bb,...,arg9=ii

Arguments amy be specified on the command line to load miscellaneous data into memory areas available to the instructions. These memory areas are 100 bytes each & may be addresssed via $arg1, $arg2, etc ... $arg9. An example follows:


 uvcopy scan1d,fild1=cobols,arg1=linage,arg2=system,arg3=i
 ==========================================================

Scan1d is 1 of the supplied pre-programmed jobs to scan a directory of text files for a pattern which may be qualified & options are available.

See the details of scan1d in SCANjobs.doc , but briefly:

   fild1=cobols - specifies the directory
   arg1=linage  - search pattern
   arg2=system  - qualifier (also present on same line)
   arg3=i       - option 'i' case insensitive, 'p' patterns, 'n' no options

If these arguments are not specified on the command line, then the job will prompt for them. This is easy to do because uvcopy stores the length of any arguments in counters: $ch1, $ch2, $ch3, ... $ch9

Note that this is simply an example of how 1 uvcopy job has assigned the meanings of the arguments; it is up to you when you write a uvcopy job to assign (& document) your own meanings.

option 'a' on 'msgw' instruction

     cmn    $ch1,0                        arg1 spcfd on command line ?
     skp>   1
     msgwa1  'enter your search pattern'

The 'a1' option causes the reply data to be stored in $arg1. This is convenient because following code can access the data in $arg regardless of whether it came from the command line or from the prompt.

Goto:   Begin this document End this document UVSI Home-Page

E6a. 'arg' - command line arguments - arg1=aa,arg2=bb, etc (continued)

argument storage areas

Argument areas are 100 bytes each & blank filled on the right

Actual memory locations are y1100(100), y1200(100), etc but it is more convenient to address as $arg1, $arg2, etc.

There is also a $arg0 at y1000(100), but this is the standard msg reply area & is usually addressed as $reply

option 'u' for arg

Option 'u' allows you to specify blanks on the command line by coding them as underscores (option u causes conversion to blank when stored).

For example, the following will scan for 'DATA DIVISION':


   uvcopy scan1d,fild1=cobols,arg1u=DATA_DIVISION
   ==============================================

Goto:   Begin this document End this document UVSI Home-Page

F0. FILE DECLARATION SET - fil__,typ,rcs,isk

F1. File Declaration Examples


 fili1=timedtl,typ=LST,rcs=80               - input file
 ============================

 filo1=timeout,typ=RST,rcs=80               - output file
 ============================

 filr1=paymaster,typ=ISF,rcs=512,isk1=0(6)  - random (keyed) file
 =========================================

 fili1=ar/customer1,typ=DBT,rcs=2048   <-- typ=DBT for 'uycopy' only
 ===================================
 - ar/customer1 defines database/table, similar format as directory/filename.

Goto:   Begin this document End this document UVSI Home-Page

F2. 'fil__' - member of file declaration set (fil,typ,rcs,isk)

fil__=filename
  • declare filename (pathname)
fili1
  • declare input file #1 - 8 max (fili1-fili8)
  • sequential fixed, variable text, or indexed sequential
filo1
  • declare output file #1 - 40 max (filo1-filo40)
  • sequential fixed, variable text, or indexed sequential
filr1
  • declare random file #1 - 8 max (fili1-fili8)
  • intended for keyed (indexed) or relative record#
  • could use for additional sequential I/O files
    if you need more than 8 'fili_'s or 40 'filo_'s
  • for output you must 1st create an empty file
fild1
  • declare directory input #1 - 8 max (fild1-fild8)
  • would read the filenames sequentially
  • could use the filename to open the file using fili1-8
    & thus read the data from all files in the directory
  • could use rcsz 80 for most UNIX implementations
    when reading the filename records from a directory
  • for examples, see 'scan2d' in SCANjobs.htm and 'rep2d'
    in REPjobs.htm.

See page 'G3' for 5 ways to declare filenames.

  1. hard-coded in the prmfile (fili1=xxx)

  2. ?default coded with a leading '?' in the prmfile. Causes a prompt 7 allows operator to change at run time

  3. specified on the command line (uvcopy jobxx,fili1=xxx). Over-rides any hard-coded filename in the prmfile

  4. null coded in the prmfile (fili1=,typ=LST,rcs=256). Searches the unix environment for symbols fili1=xxxxx, etc

  5. $environmental symbols in the prmfile (fili1=$HOME/myfile)

    define filo_ as $fili_

If your input & output files are in different directories (as recommended) it is convenient to define the output filename the same as input using '$fili_' for example:

 fili1=?dat1/weeklysales,rcs=64,typ=RSF
 filo1=?dat2/$fili1,rcs=64,typ=RSF       # define outfile same as infile

Then if you change the input filename at the prompt (caused by the '?'), you do not have to also change the name of the output file.

Goto:   Begin this document End this document UVSI Home-Page

F3. 'typ' - member of file declaration set (fil,typ,rcs,isk)

file 'typ' codes


 filo1=rpts/reportxx,typ=LSTt,rcs=132  <-- example 'typ=LSTt'
 ====================********========
typ=___
  • 3 UPPER case alpha + possible options (lower case a-z)
  • see file type options on the next page
typ=LST
  • Line Sequential file, records Terminated by LFs
  • for output the LF would be outside of the stated rcsz
    but the 't' option would truncate trailing blanks
  • for input the rcsz declared does not matter much but
    must be big enough for the longest record in the file
Note
  • use LST only when required (for variable length text records)
  • LST is 4 times slower than RSF or RST because it reads or writes
    1 character at a time (vs 1 record at a time).
typ=RSF
  • Record Sequential Fixed records (no LineFeeds)
  • mainframe sequential files
typ=RST
  • Record Sequential fixed records Terminated by linefeeds
  • the LF would be in the last byte of the stated rcsz
    (ie - within the record, not outside as for LST)
typ=RSR
  • Record Sequential Relative (Micro Focus COBOL compatible)
  • actual record size is 1 greater than declared
  • extra byte x'0A' if valid, x'00' if deleted
    on output - the x'0A' is always written
    on input - 1 extra byte is read but not tested by default
    - option 'r1' required to drop record if last byte x'00'
typ=RUF
  • UNIBOL file type
  • if input: will bypass the 8 byte header
  • if output: will create the 8 byte header as follows:
    00-05 = x'07ff00430000', 06-07 = record size in binary
typ=DBT
  • DataBase Table
  • only for 'uycopy' version of uvcopy created in November 2008
    to access SQL DataBase/Tables
  • see documentation in SQLdemo.htm#Part_2.

 fili1=ar/customer1,typ=DBT,rcs=2048   <-- typ=DBT for 'uycopy' only
 ===================================
 - ar/customer1 defines database/table, similar format as directory/filename.

Goto:   Begin this document End this document UVSI Home-Page

F3a. 'typ' - member of file set (fil,typ,rcs,isk) - continued

file 'typ' codes (continued)

typ=DIR
  • DIRectory file records
typ=ISF
  • Indexed Sequential Fixed records (D-ISAM for Micro Focus COBOL)
    (MBP-ISAM & SCO-ISAM now obsolete)
    'export ISDATEXT=.dat' - for '.dat' extensions on ISAM files
  • default is no extension on data partition (MF COBOL compatible)
  • add to /etc/profile if your site always needs .dat
           fili1=paymast,typ=ISF,rcs=512v2048,isk1=0(6)
typ=RSV
  • Record Sequential Variable files compatible with Micro Focus COBOL
    IDXFORMAT3 files, see more explanation on the next page --->
 IDXf3/IDXf8 - Indexed Sequential Variable files compatible with Micro Focus
         COBOL IDXFORMAT3 files, see more explanation 2 pages ahead --->
typ=RDW
  • 'Record Descriptor Word' variable length files
  • 4 byte record prefix with 2 byte binary record size & 2 unused nulls
  • option typ=RDWz2 for 2 byte binary only (2 nulls omitted)
  • option typ=RDWn4 for 4 byte Numeric digits (vs binary)
typ=STL
  • STandard Language file system (used by AIX CBOL)
typ=STLs
  • STL Sequential files (input & output)
typ=STLi
  • STL Indexed files (input only)
typ=STLr
  • STL Relative record files (input only)

File typ=STL Indexed & Relative is provided for input files only. You can copy them to output file types (LSTt,RSF,RST,RSV,RDW,ISF,IDXf1,& STLs Sequential).

See STL examples on page 'F9'

Goto:   Begin this document End this document UVSI Home-Page

F3b. 'typ' - member of file set (fil,typ,rcs,isk) - continued

typ=RSV MF COBOL file type IDXFORMAT3

Record Sequential Variable (typ=RSV) files are compatible with Micro Focus COBOL IDXFORMAT3 files (data partition only not indexed).

As of Nov2002 uvcopy,uvcp,& uvsort support OUTPUT as well as INPUT RSV files. Indexed Sequential Variable (typ=IDXf3/IDXf8) will be supported in January 2003 via a separate program 'uxcopy' which must be compiled with Micro Focus 'cob'.

For input record size declared does not matter, make sure it is big enough. For example:

 was=a8000b8000                          # increase area a & b to 8000
 fili1=dat1/paymast,typ=RSV,rcs=8000     # input  typ=RSV max recsize 8000
 filo1=tmp/paymast,typ=RSV,rcs=8000v500  # output typ=RSV maxrcs=8000,minrcs=500

The above would copy a Record Sequential Variable (Micro Focus IDXFORMAT3) data file to an output file of same type.

 Please see page 'G4' for more details & examples ------------->

typ=IDXf3/IDXf8 Indexed Sequential Variable files

typ=IDXf3 & typ=IDXf8 declares Indexed Sequential Variable length record files compatible with Micro Focus COBOL IDXFORMAT3 files. See the 'File Handling' documentation for Micro Focus Object or Server Express COBOL.

The Micro Focus COBOL 'EXTFH' file handler is compiled into an alternate version of uvcopy called 'uxcopy' using the 'cobccuv' script as explained in install.doc.

'uxcopy' supports the same file types as uvcopy with IDXf3/IDXf8 in addition. Two versions of the program are required since only Micro Focus COBOL users (server express 2.2+) could compile 'uxcopy' whereas any user can compile uvcopy which uses D-ISAM to support Indexed Sequential FIXED record length files.

Note that 'typ=RSV' (Record Sequential Variable with no indexed keys) files are supported by both uvcopy & uxcopy. 'uxcopy' must be used when either input or output or both files are typ=IDXf3/IDXf8

Please see uvcopy6.htm for test/demo uxcopy jobs to read/write IDXf3/IDXf8.

Goto:   Begin this document End this document UVSI Home-Page

F4. uvcopy 'file typ' options

 fili1=testinp,typ=RSFb16m500,rcs=128
                      *******             - typ option examples
 filo1=testout,typ=LSTdtw,rcs=128         - lower case suffixes to typ
                      ***
a
  • append to the file's existing contents
    (vs default of erasing existing contents)
b1
  • reduce multiple blank lines to 1 blank line
b2
  • remove ALL blank lines
c1
  • convert unprintable characters to periods
c2
  • convert unprintable characters to blanks
c4
  • convert tabs x'09' to 4 blanks
c8
  • convert tabs x'09' to 1 blank
c__
  • apply to typ=LST files input &/or output
d1
  • insert record terminator CR x'0D' for typ=LST & typ=RST files
    (a single CR vs LF for unix vs CRLF for DOS option d1)
  • CR is appended for output records & removed from input records
  • may use this for McIntosh files
d2
  • inserts LF x'0A' on output, remove on input (typ=LST & typ=RST files)
  • d2 is the default (for UNIX files)
d3
  • MSDOS file, inserts CR (and LF) when writing typ=LST/RST files
  • removes when reading into the input area
d4
  • insert null as terminator on output typ=LST files
d8
  • insert tilde as terminator on output typ=LST files
e2
  • insert EBCDIC Line-Feed x'25' in last byte of record (typ=RSTe2)
e1
  • insert Carriage-Return x'0D' in 2nd last byte (use with e2+e1=e3)
e3
  • insert CR+LF in last 2 bytes of record (applies only to 'typ=RSTe3'
f#
  • format for typ=IDX files
f1
  • fixed length Indexed records, compatible with C-ISAM, same as typ=RSF
f3
  • variable length Indexed files (file size < 2 gig)
f8
  • variable length Indexed files (allowing file size > 2 gig)
  • IDXF3 & IDXf8 could be fixed records in variable format
Note
  • see page 'F7' since option 'f' is related to options 'v' 'x' 'y'
g_
  • get data types for file typ=IDXf3/IDXf8/RSV
g4
  • get active data records (default)
g2
  • get deleted data records
g6
  • get both

Goto:   Begin this document End this document UVSI Home-Page

F5. uvcopy 'file typ' options (continued)

g#
  • delimited input file, applies only to typ=LSTg#
    g# is numeric value of the delimiter character
    example: g124 specifies the pipe symbol '|' x'7C'
  • for uvqrpg only as of Feb 2008 (not yet uvcopy)
i#
  • copy ISAM file keys from input fili#
i1
  • coded on the output file type, for example filo1 typ=ISFi1
i8
    would copy ISAM keys from the fili1 previously declared.
j1
  • translate filename to lower case (before opening)
j2
  • translate filename to UPPER case (before opening)
j4
  • translate any extension to the opposite case

Option 'j' useful when you are processing all files in directory (with uvcopyx) And you want the output files in a different case than input files.

k#
  • set key of reference for an indexed (ISAM) file
k1
  • default retrieval sequence is via key #1
k9
  • (typ=ISFk9) causes retrieval in sequence by key #9
l0
  • No record locking
l1
  • read only file locking
l2
  • AUTOLOCK (applies only to ISAM files)
  • only 1 record locked at 1 time in this file
  • records are locked by the 'red' instruction
    & unlocked by whatever instruction follows
    (might be 'upd' to update the record)
l4
  • MANULOCK (applies only to ISAM files)
  • assumes the programmer will handle locking manually
    using the 'lck' uvcopy instruction ('islock' DISAM function)
  • Use this option if you want to open 2 paths for the same file
    (fili1 & filr1 for the same filename with typ=ISFl4)
l8
  • NO locking, used only for Non-Indexed Sequential files
  • For non-indexed files, only lock options l0, l1, l8 apply.
Note
  • it is easier to use the 'FILE locking' options
    (l0,l1 for ISAM files; l0,l1,l8 for Sequential files)
    if you do NOT need to run 2 jobs at same time updating the same file
Note
  • You must code 'typ=ISFl4' (MANULOCK) on the ISAM file declaration
    to use the locking options on ISAM read & update instructions
    ('redm5l4' to read key= with lock & 'updl4' to update & release the lock)
m____
  • monitor option (report progress every ____ records)
  • applies to both input & output files (not random)
m1000000
  • default is every 1,000,000 records
m50000
  • would report every 50,000 records (m0 would inhibit)

Goto:   Begin this document End this document UVSI Home-Page

F6. uvcopy 'file typ' options (continued)

n1
  • inhibit error msg if record data length exceeds rcsz specified
  • for typ=LST files where you know there are some exceptionally long
    records you want to split these records without notification
n4
  • typ=RDW: specifies 4 byte record-size prefix Numeric digits
  • for 'typ=RDW' Record Descriptor Word variable length files
  • option typ=RDWn4 for 4 byte Numeric digits (vs binary)
  • also see typ=RDWz2 for 2 byte binary only
  • also see typ=RDWz4 for 2 byte binary + 2 bytes null (4 byte prefix)
p___
  • permissions to be given to the file when closed
p777
  • would set read,write,execute permission for owner,group,& others
  • when omitted, the system defaults apply (umask in /etc/profile)
r1
  • for typ=RSRr1 Relative files (MicroFocus COBOL compatible)
  • drop record if extra byte = x'00'
s0
  • default displays EOF statistics for all file types
s1
  • inhibit the basic EOF stats line for all file types
s2
  • inhibit the 1 line ISAM summary statistics
s4
  • requests the detailed key statistics lines
    showing key start,length,type for each key
t
  • truncate trailing blanks on output typ=LST files
  • the Line Feed will be inserted after the last nonblank
    rather than at the end of the specified record size
t4
  • write output recsize same as last input recsize
  • LSTt4 inhibits the usual LSTt effect of shortening to last non-blank
    (allows trailing blanks to remain as on input record)
u
  • UNIX system file unbuffered (open/read vs fopen/fread)
  • required for 9 track tape reads on 2145-03
    especially for unlabeled tapes where block size is unknown
    (see job t9copy2 in section TAPEjobs.doc)
Note
  • see option 'v' on the next page
  • variable record size for typ=ISF & typ=IDXf3/IDXf8 Indexed files
w1
  • signal EOF if x'1A' found in 1st byte of any record
  • applies to typ=LST,typ=RSF,typ=RST,typ=RSR
w2
  • warning for existing output files to be over-written
  • prompts to Overwrite, Rename, Append, @autoAppend @A,@B,@C,etc, Failjob
  • reply O/R/A/@/F
  • '@' for auto append (determines next alpha in series @A,@B,@C,etc
w6
  • inhibit the prompt, automatically append @A,@B,@C,etc
    (option w2 + w4 = w6)
w8
  • roundup output record size (pad x'20's) to multiple of 8 (vs multiple 4)
  • applies only to typ=RSVw8 output

Goto:   Begin this document End this document UVSI Home-Page

F7. uvcopy 'file typ' options (continued)

file typ options for typ=IDX & typ=RSV

Note
  • these options apply only to 'uxcopy' (not 'uvcopy')
  • 'uxcopy' includes the Micro Focus COBOL file handler (EXTFH)
  • to support variable length Indexed files
IDXf1
  • fixed length Indexed records, compatible with C-ISAM, same as typ=RSF
IDXf3
  • variable length Indexed files (file size < 2 gig)
IDXf8
  • variable length Indexed files (allowing file size > 2 gig)
  • IDXF3 & IDXf8 could be fixed records in variable format
v9999
  • minimum record size option for typ=IDX & typ=RSV files
    For example: 'typ=IDXv400,rcs=5000' v400 declares minimum size 400
    while rcs=5000 declares the maximum size 5000.
  • if option v not specified & record-length specified in op2 of 'put'
    output records will be the same size, but with record headers
  • if option v not specified & record-length NOT specified in op2 of put
    output records size taken from register 'v', which is set by last
    input 'get', but may be set explicitly with instrn 'mvn'
  • also see type 'y4' below to determine record size by scanning back
    from max size to the last nonblank/nonnull beyond min size
  • any option 'v' forces option 'y2' (variable format)
v#w8
  • w8 roundup output record size (pad x'20's) to multiple of 8 (vs 4)
x
  • file organization for typ=IDX files
x1
  • Sequential, no Index created
x2
  • Indexed, assumed if 'isk' (Indexed Seqntl Key) is declared
y
  • Recording Mode
y1
  • Fixed Length records, all records forced to size spcfd by rcs=____
  • default for if option 'v' NOT specified (w or w/o min recsize)
y2
  • Variable Length records
  • default if option 'v' IS specified (w or w/o min recsize value)
  • min recsize specified by option 'v', max recsize by rcs=____
y4
  • determine the record size for each record by scanning back from
    max size to last non-blank or non-null beyond the min size
y8
  • fixed length records in variable length format
  • in case you want to copy a variable length file & output all records
    as the max size specified on rcs=___ (but in variable length format
 z4   - RDW, variable lth, recsize 1st 2 bytes binary, bytes 3&4 x'0000'
        recsize includes prefix-size + data-size (z/z0 default z4)
 z2   - RDW, prefix 2 bytes only, recsize excludes prefix size
      - used by FTP programs for transferring mainframe files to unix/linux
 z8  - same as RDWz4, but bypasses any BDW prefixes, processes only RDW records
 z1  - little-end binary vs default Big-end binary, combine with z2/z4/z8
     - z2/z4/z8 Big-end binary (default), specify z3/z5/z9 for little-end binary
n4
  • also note option n4 = 4 byte recsize Numeric digits (vs Binary)

Goto:   Begin this document End this document UVSI Home-Page

F8. uvcopy 'file typ' options (continued)

file typ option 'v' varlth records C-ISAM/D-ISAM

v#
  • min recsize for typ=ISF C-ISAM/D-ISAM variable length Indexed files
  • max recsize specified by rcs=___
note
  • above variable length C-ISAM indexed files NOT compatible with MF COBOL
  • UVSI recommends following IDXf3/IDXf8 for variable length Indexed files
  • Micro Focus COBOL compatible
  • see uvcopy8.htm for test/demo uxcopy jobs to read/write IDXf3/IDXf8.

variable length output record size

If output record size is explicitly specified on op2 of the 'put' instruction, then the variable length record will be written with that record size.

But if op2 of the 'put' is not specified, then the record size will be taken from register 'v' ($rv), which is probably the last input record size since the 'get' instruction stores the record length in $rv.

Goto:   Begin this document End this document UVSI Home-Page

F9. 'file typ' options (continued)

overriding parameter file 'typ' on command line

Use typi1, typo1, typr1, typi2, etc to override the parameter file options.

For example if you want to change the input ISAM file lock option to 'l1' The parameter fili1 definition & command line to override might be:


 fili1=MSTR/paymas,typ=ISF,rcs=512                <-- parameter file definition
 =================================

 uvcopy paymas.tbl,fili1=MSTR/paymas,typi1=ISFl1  <-- command line
 ===============================================
                                        ^^
 The 'i1' option on 'typi1' is required because without this 'typ=ISFl1'
 alone would modify the 'filo1' definition (whatever file was declared last).

option to solicit file types at run time

If the 1st char of the 'typ' assignment in the parameter file is a '?' then the file typ will be solicited from the operator at execution time.

      fili1=abcfile,rcs=80,typ=?ISFl0

The operator might reply 'ISFl4' for NOLOCK, but this is just 1 example, any options could be specified in this manner.

Goto:   Begin this document End this document UVSI Home-Page

G1. 'rcs' - member of file set (fil,typ,rcs,isk)

File declaration examples

 fili1=timedtl,typ=LST,rcs=80                  - input file
 filo1=timeout,typ=RST,rcs=80                  - output file
 filr1=paymaster,typ=ISF,rcs=512,isk1=0(6)     - random (keyed) file

'rcs' - declare record size

rcs
  • declares record size for the preceding fil__ file
rcs=80
  • declare record size 80 bytes
  • there is no limit on the maximum record size, but you would need
    to increase the read/write areas used. Areas 'a'-'t' default to
    4096 bytes & may be increased via: was=a8000b16000c25000...etc..
    (see the 'was' function on page 'E5')
rcs=8192
  • declare record size 8192 bytes
Note
  • work areas (a-t) are available to get/put records
  • the work areas default to 4096 bytes & you must increase if your
    record size larger. So for rcs=8192, you must use the 'was'
    (Work Area Size) which may appear just prior to fili/filo
  • for example if work area 'a' is intended for fili1, code as follows:

was=a8192 fili1=xxxx,rcs=8192,typ=RSF

Note
  • For variable-length text files (typ=LST), the record size does
    not matter, as long as it is big enough.
  • For fixed-length files (RSF & RST), the 'rcs' should match the
    actual file record-size.

Goto:   Begin this document End this document UVSI Home-Page

G2. 'isk' - member of file declaration set (fil,typ,rcs,isk)

isk_
  • declare keys for the preceding file (isk1-isk9 max)
  • required only for output files (creating new file)
    but may be specified for documentation on input or random

 filo1=test,rcs=256,typ=ISF,isk1=0(8),isk2=40(15),isk3=70(10)...isk9=999(9)
 ==========================================================================
isk1=0(8)
  • declare 1st key columns 1-9
isk2=40(15)
  • declare 2nd key columns 41-45
isk3=70(10)
  • declare 3nd key columns 71-80
isk9=999(9)
  • declare 9th key columns 1000-1008
DUPS/NODUPS
  • option may be coded within the length using 'd' or 'n'
  • default is nodups on key#1 & dups allowed on keys 2-9
isk1=9(9n)
  • the default ('n' for nodups) on key#1 (no need to code)
isk2=9(9d)
  • the default ('d' for dups) on key#2-9 (no need to code)
isk1=9(9d)
  • must code the 'd' if you want dups allowed on key#1
isk2=9(9n)
  • must code the 'n' if you want nodups on keys 2-9

multi-part keys

 isk1p1=0(8)       # declare key#1 part#1
 isk1p2=20(6)      # declare key#1 part#2
 isk1p3=30(4)      # declare key#1 part#3
 isk2p1=100(30)    # declare key#2 part#1
 isk2p2=150(15)    # declare key#2 part#2

or all on 1 line

 isk1p1=0(8),isk1p2=20(6),isk1p3=30(4),isk2p1=100(30),isk2p2=150(15)

Goto:   Begin this document End this document UVSI Home-Page

G2a. 'isk' - member of file declaration set (fil,typ,rcs,isk)

alternate format for ISAM key specs


 filo1=test,rcs=256,typ=ISF,isks=(0,8,40,15,70,10,999,9)
 =======================================================

 filo1=test,rcs=256,typ=ISF,isks=(0,8n,40,15d,70,10d,999,9d)
 ===========================================================

 filo1=test,rcs=256,typ=ISF,isks=(0,8d,40,15n,70,10,999,9)
 =========================================================

option to copy output ISAM keys from input file

fili1=infile,rcs=256,typ=ISF filo1=outfile,rcs=256,typ=ISFi1 <-- note option 'i1' on typ=ISFi1

Goto:   Begin this document End this document UVSI Home-Page

G3. uvcopy file declaration - 5 ways to specify filenames

  1. via 'fil__=filename' keywords in the parameter file (fili1-fili8,filo1-filo40,filr1-filr8,fild1-fild8)

  2. via 'fil__=?defaultfilename' in the parameter file leading '?' causes prompt to accept default or enter alternate filename

  3. via 'fil__=xx' keywords on command line overriding fil__ hard-coded in the parameter file

  4. via 'fil__=,' null in prmfile causes search of unix environment for exported symbols 'export fil__=xxxx' (use in scripts)

  5. via any unix environmental symbols coded in the prmfile 'fili1=$HOME/myfile'

    File Declaration - Examples

  6. paramfile: fili1=custmas1,typ=ISF,rcs=256 command line: uvcopy paramfile

  7. paramfile: fili1=?custmas1,typ=ISF,rcs=256 command line: uvcopy paramfile prompt: ?custmas = default fileout, null to accept or rekey

  8. paramfile: fili1=custmas1,typ=ISF,rcs=256 command line: uvcopy paramfile,fili1=custbak,filo1=tmp/report1

  9. paramfile: fili1=,typ=ISF,rcs=256 command line: uvcopy paramfile unix script: export fili1=custmas uvcopy paramfile

  10. paramfile: fili1=$HOME/myfile,typ=ISF,rcs=256 fili1=?$HOME/myfile,typ=ISF,rcs=256 (use ? for prompt) command line: uvcopy paramfile

    File Declaration Notes

  11. any redefinition of fil__ on the command line will override any definitions in the paramfile.

  12. the fil__=,filo1=, (null equates) in the paramfile indicate that the environment is to be searched for the fil__ keywords & their corresponding values are to be used for the filenames. Also note that any fil__ keywords on the command line would override any environmental values.

  13. As of 9702 you can code any exported environmental symbol in the param file & the environment will be searched for the value

Goto:   Begin this document End this document UVSI Home-Page

G4. Record Sequential Variable (RSV) & Indexed Sequential Variable (ID Xf3)

As of Nov 2002 'typ=RSV' supports OUTPUT files as well as INPUT files. 'typ=RSV' provides compatibility with Micro Focus COBOL IDXFORMAT3 Variable length files, but only for Sequential. Indexed Sequential Variable (typ=IDXf3) length support was added in Jan 2003 by an alternate version of uvcopy (uxcopy linked with EXTFH file handler from Micro Focus COBOL).

For complete documentation on these files, please see the 'FILE STRUCTURES' chapter in Micro Focus Object COBOL or Server Express COBOL, or the web site http://supportline.microfocus.com/documentation/books/ocds4140/fhfile.htm.

'typ=RSV' files have 128 byte file header. Each record has 2 or 4 byte record header/prefix which has x'40' in the first nibble to identify a data record, followed by the record size in the next 12 bits or 28 bits, depending on max recsize <= 4095 or > 4095 bytes.

typ=RSV & typ=IDXf3 sample file I/O

 was=a8000b8000                          # increase area a & b to 8000
                                         # (if max rcsz > 4096 default)
 fili1=dat1/paymast,typ=RSV,rcs=8000     # input  typ=RSV max recsize 8000
 filo1=tmp/paymast,typ=RSV,rcs=8000v500  # output typ=RSV maxrcs=8000,minrcs=500
 filo2=tmp/pm,typ=IDXf3,rcs=8000v500,isk1=0(6)  # typ=IDXf3 Indexed Seqntl Key
  1. The maximum rcsz is specified by 'rcs=____' & the minimum rcsz is specified by option 'v' of 'typ=RSVv____'. Record size determined by scanning backward to last non-blank & round up to a multiple of 4 (includes 2/4 byte rec hdr).

  2. If minimum rcsz (option v) is not specified, all output records will be written with maximum record size & blank padded as necessary. File option 'z3' with option 'v' (typ=RSVv80z3) forces recsize to only maximum or minimum.

  3. You may specify any combination of I/O file types (LST,RSF,ISF,RSV,IDX) which means you can convert files from any type to any other type. For example you can create test files by using 'vi' to create text records & then use uvcp,uvsort,uvcopy,&/or uxcopy to convert the text file (typ=LST) to typ=RSV or typ=IDXf3/IDXf8 output file.

Goto:   Begin this document End this document UVSI Home-Page

G4a. Record Sequential Variable length files (typ=RSV)

typ=RSV/IDX examples for uvcopy

 fili1=dat1/paymast,typ=RSV,rcs=8000     # input  typ=RSV max recsize 8000
 filo1=tmp/paymast,typ=RSV,rcs=8000v500  # output typ=RSV maxrcs=8000,minrcs=500
 filo2=tmp/pm,typ=IDXf3,rcs=8000v500,isk1=0(6)  # typ=IDXf3 Indexed Seqntl Key

typ=RSV/IDX examples using uvcp

Note
  • uvcp is used to illustrate file typ=RSV/IDX, since it is more concise
  • we can specify the complete file I/O on 1 line

 1. uvcp "fili1=dat1/test1,rcs=256,typ=LST,filo1=tmp/test1a,rcs=254,typ=RSV"
    ========================================================================

 2. uvcp "fili1=dat1/test1,rcs=256,typ=LST,filo1=tmp/test1b,rcs=254,typ=RSVv80"
    ============================================================================

The output records will vary from 84 bytes to 256 bytes depending on the position of the last nonblank in the record data. Note that the record length must be a multiple of 4 so 2 byte fill is added if required.


 3. uvcp "fili1=dat1/test1,rcs=256,typ=LST,filo1=tmp/test1c,rcs=5000,typ=RSVv400"
    =============================================================================

This example writes 4 byte record headers (vs 2 bytes in above examples) because the maximum record size is > 4095 bytes (rcs=5000).

Goto:   Begin this document End this document UVSI Home-Page

G4b. Record Sequential Variable length files (typ=RSV)

using uvcp to create a typ=RSV file


 2. uvcp "fili1=dat1/testRSV3,rcs=256,typ=LST,filo1=tmp/test3,rcs=254,typ=RSVv80"
    =============================================================================

input text file (3 records)


 #1 testRSV3 - text to create Rec Seqntl Variable(RSV) file to test uvcp&uvsort
 #2 uvcp "fili1=dat1/testRSV3,rcs=256,typ=LST,filo1=tmp/testx,rcs=254,typ=RSVv80"
 #3 output records vary from min(82) to max(256) depending on last nonblank-----|
 -----this record will be 164 (data 160 + 2 byte rechdr + 2 round to multiple 4)---->

output RSV file (displayed with uvhd)


 uvhd tmp/testx v      <-- display file using uvhd with option 'v'
 ================
                       1         2         3         4         5         6
 r#        1 0123456789012345678901234567890123456789012345678901234567890123
           0 0~......030114102019.................>.......................P..
             370000003333333333330000000000000000030000000000000000000F000500
             0E00000003011410201900000000000000000E0100000000100000000E000000
          64 ................................................................
             0000000000000000000000000000000000000000000000000000000000000000
             0000000000000000000000000000000000000000000000000000000000000000
                       1         2         3         4         5         6
 r#        2 0123456789012345678901234567890123456789012345678901234567890123
         128 @P#1 testRSV3 - text to create Rec Seqntl Variable (RSV) file to
             4523276775553222767727626766762566256767625676666622555226666276
             00310453423630D0458404F032514502530351E4C0612912C5082369069C504F
          64  test uvcp/uvsort
             27677277672777677222
             0453405630F563F24000
                       1         2         3         4         5         6
 r#        3 0123456789012345678901234567890123456789012345678901234567890123
         212 @P#2 uvcp "fili1=dat1/testRSV3,rcs=256,typ=LST,filo1=tmp/test3,r
             4523277672266663366732767755532767333327773455266663376727677327
             0032056300269C91D4141F45342363C233D256C490DC34C69CF1D4D0F45343C2
          64 cs=254,typ=RSVv80"
             67333327773555733222
             33D254C490D236680200
                       1         2         3         4         5         6
 r#        4 0123456789012345678901234567890123456789012345678901234567890123
         296 @.#3 output records vary from min(84) to max(256) depending on l
             4A23267777727666767276772676626662332276266723332266766666626626
             00330F540540253F24306129062FD0D9E884904F0D188256904505E49E70FE0C
          64 ast nonblank-----|-----this record will be 164 (data 160 + 2 byt
             6772666666662222272222276672766676276662662333226676233322232677
             1340EFE2C1EBDDDDDCDDDDD48930253F24079CC025016408414101600B020294
         128 e rechdr + 2 round to multiple 4)---->
             627666672223276766276267672322222322
             502538420B0202F5E404F0D5C4049DDDDE00

Goto:   Begin this document End this document UVSI Home-Page

G4c. Record Sequential Variable length files (typ=RSV)

File Header record for typ=RSV files

                       1         2         3         4         5         6
 r#        1 0123456789012345678901234567890123456789012345678901234567890123
           0 0~......021125110120.................>.......................~..
             370000003333333333330000000000000000030000000000000000000F000700
             0E00000002112511012000000000000000000E0100000000100000000E000E00
          64 ................................................................
             0000000000000000000000000000000000000000000000000000000000000000
             0000000000000000000000000000000000000000000000000000000000000000

00-00 - x'30' identifies the file header record (vs x'40' for data records)

 01-01 - data size of this record x'7E' = (7*16+14*1) = 112+14 = 126
       - total size is 128 including the 2 byte record header
 00-03 - If max rcsz > 4095, the record header would be 4 bytes x'3000007C'
       - 7*16 + 12*1) = 112+12 = 124 + 4 byte header = 128 total record size

08-19 - file creation date/time stamp (yymmddHHMMSS)

36-36 - reserved value x'3E' required for Micro Focus COBOL IDXFORMAT3 files

39-39 - file ORGanization x'01' = Sequential

48-48 - Recording Mode x'01' = Variable format

 54-57 - Maximum record length
       - In this example x'000000FE' = (15*16+14*1) = 240+14 = 254
 58-61 - Minimum record length
       - In this example x'0000007E' = (07*16+14*1) = 112+14 = 126

Goto:   Begin this document End this document UVSI Home-Page

G5. file type STL

File 'typ=STL' is the STandard Language file system used by AIX COBOL, added to uvsort in February 2016. These are complex file formats with file headers & record headers. There are 3 subtypes as follows:

typ=STLs
  • STL Sequential files (input & output)
typ=STLi
  • STL Indexed files (input only)
typ=STLr
  • STL Relative record files (input only)

File typ=STL Indexed & Relative is provided for input files only. You can copy them to output file types (LSTt,RSF,RST,RSV,RDW,ISF,IDXf1,& STLs Sequential).

test uvcopy STLs to LSTt

 # testSTLs - test reading STL Sequential
 #          - by Owen Townsend, UV Software, Feb 22/2016
 # testSTL  - alternate job to test all 3 formats
 fili1=dat1/testSTLs,rcs=4096,typ=STLs
 filo1=tmp/teststls,rcs=256,typ=LSTt
 @run
         opn    all
 #
 man20   get    fili1,a0
         skp>   man90
         put    filo1,a0
         skp    man20
 #
 # EOF - close files & end job
 man90   cls    all
         eoj

We specify 'rcs=4096' or a size you know is larger than the largest record expected. Record size specified by rcs=... will init I/O areas to blanks, The actual record size is specified in the file header &/or as a prefix on each record & could vary from record to record.

Output 'typ=LSTt' inserts a LineFeed x'0A' after the last nonblank, truncating records depending on data present. So the output records could vary from 4096 bytes down to 1 byte.

executing uvcopy job


 uvcopy pf/testSTLs
 ==================
 /home/userxx
 :-----pf/testSTLs      <-- uvcopy job
 :-----dat1/testSTLs    <-- input data file
 :-----tmp/teststls     <-- output file

 uvcopy testSTLs        <-- may omit directory if uvcopy job stored in $HOME/pf
 ===============          - see export PFPATH=$HOME/pf:...:... in profile

Goto:   Begin this document End this document UVSI Home-Page

G6. file type STL

test uvcopy STLi to STLs

 # testSTLis - test STL copy  STLi to STLS (Indexed to Sequential)
 #           - by Owen Townsend, UV Software, Mar05/2016
 #
 fili1=dalestl.outseq.ism,rcs=4096,typ=STLi
 filo1=tmp/teststls,rcs=200,typ=STLs
 @run
         opn    all
 #
 man22   get    fili1,a0
         skp>   man90
         put    filo1,a0
         skp    man22
 # EOF - close files & end job
 man90   cls    all
         eoj
Note
  • omitting record size on put - will use size from input record
  • known to be 91 for this test
  • if you did want output size 200 bytes, specify on put as follows:

        put    filo1,a0(200)  <-- specify size on put if known fixed size desired
        ====================    - to use size different than input record

 filo1=tmp/teststls,rcs=200,typ=STLsy4  <-- option 'y4' on filo1 typ=STLsy4
 =====================================    - sets recsize at last non-blank

STL file formats

See STL file formats documented at http://uvsoftware.ca/uvhd.htm#5J1

'uvhd' allows you to see the file header records & the record prefixes but 'uvsort' & 'uvcp' will extract only the data records.


 uvhd dat1/testSTLs      <-- will show file header (112 bytes)
 ==================

 uvhd dat1/testSTLs x2   <-- option 'x2' for STL Sequential
 =====================     - use 'x4' for Indexed & 'x8' for Relative

Goto:   Begin this document End this document UVSI Home-Page

H1. 'lod' - load a table of data into a work area (a-w)

H1. lod - load data into a table work area (a-w)

  'lod' - load a table of data into the op1 area
          from embedded text in prmtr file *or* from a file
        - 'lod' is a function, not an instruction which means
          it is coded before @run & its action occurs once at setup time
          vs instructions which follow @run & are not executed until
          all instructions are stored but then may possibly be
          executed many times
        - the table 'lod'ed may be looked-up by the 'lok' instruction
          at execution (run) time
        - could 'lod' equated $symbols into area q for address
          substitution as instructions are loaded from prm file
Example
  • load 20 bytes from each line following, into area 'h'
 lod=h0(20)
 aa=ardvarks
 bb=bumblebees
 cc=cats
  ...
 zz=zebras
 ~~              <-- end of data marker '~~' in 1st 2 bytes of table entry
                   - also terminated by x'0000'

'lok' instruction used with previously 'lod'ed tables

    lok   h0(20),'bb'          - look up a table in area 'h' of 20 byte
                                 entries, using 2 byte argument 'bb'
    lok   j0(20),a20(2)        - look up a table in area 'j' of 20 byte
                                 entries, using 2 byte argument of
                                 whatever data is in bytes 21-22 of 'a'

lodc1=h0(20) <-- option 'c1' to bypass any #comment lines ('#' column 1)

 lodc1v1        <-- option 'v1' to expand any $symbols in data
 lodc1v2        <-- option 'v2' to expand any ${symbols} in data
 lodc1v3        <-- option 'v3' to expand both $symbols & ${symbols}
 lodc1v3h       <-- option 'h' to convert hex representation to true hex
 Please see more options & examples on the next page --------------->
Note
  • also see the 'rtb' (read table file) instruction which is similar
    but loads a table from a file vs embedded data.

Goto:   Begin this document End this document UVSI Home-Page

H1a. lod function options

option 'h'
  • convert hex representations to true hex data

lodh=k0(8) 0001020304050607 08090A0B0C0D0E0F ~~ This example will convert each entry of 16 bytes of hex representation to 8 bytes of true hex/binary data while being loaded into the table area

option v1
  • expand uvcopy $symbols
  • expand unix environmental variables ${symbols}
  • expand both $symbols & ${symbols}
 lodv3=k0(80)
 $jobname x--pageheading--x $datetime user=${LOGNAME} home=${HOME}
 ~~
   - $jobname will be converted to the name of the uvcopy prmfile
   - $datetime will be converted to system date/time (YYYY/MM/DD_HH:MM:SS)
   - ${LOGNAME} will be converted to the exported value of LOGNAME, etc

loading $symbols in area 'q'

uvcopy & uvqrpg allow you to lod area 'q' with $symbols for use on following instructions. For example, you could load area 'q' with $field defs as follows & use the definitions in the following instructions.

 lod=q0(48)                # load $symbol table
 $cust            =a0(6)
 $prod            =a30(6)
 $qty                     =a38(6)
 $price                           =a45(7)
 $amt                             =a53(9)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # field definitions are staggered above to demonstrate FREE FORMAT
 # might use $symbols to recalculate qty*price as follows:
        mvn    $amt,$qty           move quantity to amount field
        mpy    $amt,$price         qty * price = amt

See next page for a complete job demonstrating area 'q' $symbols --->

Goto:   Begin this document End this document UVSI Home-Page

H1b. lod function options

 # slrpt3 - demonstrate using $symbols to define record field locations
 #        - note 'lod=q0(48)' with $symbols to define record fields
 #
 # uvcopy slrpt3   <-- list sales cust#,prod#,qty,price,&amt & verify qty*price
 # =============
 #                      ** sample report **
 # slrpt3 - List sales records & verify qty*price  2009/06/17_10:40:11
 # cust# product# quantity       price        amount     qty*price
 # 130140  SCR012       21       10.01        210.21
 # 130140  CHR001       22       20.02        440.22        440,44  qty*price ERR
 # 139923  TAB013       23       30.01        690.23
 #
 rop=r1   # prompt for outfile disposition at EOJ
 fili1=?dat1/sales2,typ=RSF,rcs=64       #input file (see layout in uvtrain.doc)
 filo1=?tmp/$fili1.rpt,typ=LSTt,rcs=128  #output file, for subsequent more/vi/lp
 lod=q0(48)                # load $symbol table
 $cust            =a0(6)
 $prod            =a30(6)
 $qty                     =a38(6)
 $price                           =a45(7)
 $amt                             =a53(9)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #note    - above area 'q' $symbol entries staggered to test FREE FORMAT
 #Jan2008 - entries increased from 32 ('=' col 18) to 48 with '=' in col 34
 #Jun2009 - $symbol entries FREE FORMAT, '=' shifted to col 34 for fixed lookup
 #
 # load table of report headings
 lodv1=h0(100)
 $jobname - List sales records & verify qty*price  $datetime
 cust# product# quantity       price        amount     qty*price
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 @run
        opn    all                    open files
        wtbe   filo1,h0(100),h0(100)  write report headings table
 # begin loop to get records, edit & write line to report file (until EOF)
 loop   get    fili1,a0               get next record
        skp>   eof                    (cc set > at EOF)
        mvc    b0(6),$cust            move cust# from area a to are b
        mvc    b8(6),$prod                  move product#
        edt    b16(8),$qty,'zzz,zz9-'       edit qty
        edt    b26(10),$price,'zz,zzz.99-'  edit price
        edt    b38(12),$amt,'zzzz,zzz.99-'  edit amt to out area
        mvn    $ca1,$qty              move qty to work ctr for extension
        mpy    $ca1,$price            qty * price to verify existing amt
        cmn    $ca1,$amt              match existing amt ?
        skp=   2
        edt    b52(12),$ca1,'zzzz,zzz,99-'  edit qty*price
        mvf    b66(20),'qty*price ERR'
        putb   filo1,b0               write line to output file
        skp    loop                   repeat loop
 # EOF - close files & end job
 eof    cls    all
        eoj

Goto:   Begin this document End this document UVSI Home-Page

H1c. lod function options

area 'q' $symbol tables

You may store $symbol field definitions in files (like COBOL copybooks) and load them at execution time. The tablefiles must be stored in the directory defined by 'fild7'. For example if the directory is 'uvsymbols' & 'empsyms' is 1 of the files in that driectory.

 fild7=/home/appsadm/uvsymbols  # declare directory of $symbol table files
 lod=qq0(48),empsyms,b          # load tablefile 'empsyms', change area to 'b'

In this example 'uvsymbols' is a directory containing several files of $symbols for field locations in various files. 'empsyms' would be a file of $symbols for the employee master record. operand 3 (b) in this example is an area override to change the area coded in the file.

Note the 2nd 'q' of qq0(48) is a register (optional) which allows continuing to lod area q from prior 'lod's. This allows you to load $symbols from several different $symbol files

lod=qq0(48),custmaster lod=qq0(48),salesdtl,b lod=qq0(48),products,c

Goto:   Begin this document End this document UVSI Home-Page

H2. '@run' - declare end of functions & beginning of instructions

'@run' must follow the functions declared (fil__,typ,rcs,etc) & precede the instructions (opn,get,put,mvc,add,sub,etc)

The following parameter file illustrates this & as well illustrates a 'minimum' parameter file - enough to simply copy a file.

This would be a useful skeleton that you would use when creating new parameter files - just modify filenames, types, records sizes, & plug your instructions into the '---' line marked below.

minimum 'skeleton' uvcopy parameter file

 # skeleton - uvcopy template job, copy/rename/modify & modify as required'
 #          - be sure to update these lines with new name & job description'
 opr='$jobname - uvcopy skeleton job, copy/rename & modify as required'
 fili1=?input,typ=LST,rcs=256       # code filenames or leave ? for prompt
 filo1=?$jobname.tmp,typ=LSTt,rcs=256  #
 @run
       opn   all                    open files
 # begin loop to get & put records until EOF
 loop  get   fili1,a0               get record into area 'a'
       skp>  eof                    (condition code set > at EOF)
 #-----------------------------
       mvc   b0(256),a0             move input record to output area 'b'
 #     ---   -----,-----            ** add your instructions here **
 #-----------------------------
       put   filo1,b0               write record to output file
       skp   loop                   return to get next record
 #
 eof   cls   all                    close files
       eoj                          end job

Unmodified this job would copy variable length text records (max 256) unchanged to the output file, except for truncation of trailing blanks due to the 't' option of 'LSTt'. Uvcopy would also convert null records (line feed only) to 1 blank + LF useful because some printers drop line with line feeds only.

It is sometimes useful to create variable length test data with editor & then convert to fixed length (often required by cobol programs). For example, if you wanted to create a file of 80 byte fixed length records, you would only have to change the output file 'typ' & 'rcs'

 filo1=?$jobname.tmp,typ=LSTt,rcs=256      <-- from this
                      ^^^^     ^^^
 filo1=?$jobname.tmp,typ=RSF,rcs=80        <-- to this
                      ^^^     ^^

Goto:   Begin this document End this document UVSI Home-Page

H3. '@pf2' - declare 2nd file of instructions to be loaded at run time


 @pf2=paramfile2   - declare 2nd file of instructions to be loaded at run time
 ===============

See 'dateage1' in AGEjobs.doc for a good example of this technique.

Dateage1 is a master uvcopy job that generates multiple worker uvcopy jobs to increment date fields in possibly hundreds of data files. The worker jobs include 1 'bal' instruction for each date field to be incremented. There are about 10 different subrtns provided depending on the date format.

Only 1 copy of these date-field-increment subrtns is required because each worker job loads them at run-time. Here is a sample of 1 of these generated jobs & note the '@pf2' function which is last in the job.

 opr='warmas1 warmas1 - generated by cobmap1,dateage1,uvdata52'
 uop=q1d365e1v1970w10q0i7d730            <-- options from dateage1 generation
 was=a15000b15000
 fili1=tf1/warmas1,rcs=00064,typ=RSF
 filo1=tf2/warmas1,rcs=00064,typ=RSF
 @run
        opn    all
 loop   get    fili1,a0
        skp>   eof
        mvc    b0(00064),a0
 #
        bal    upd60,'a0030b006  ','wm-purchase'    <-- Note 'bal' subrtns
        bal    upd20,'a0044b002  ','wm-exp-year'
 #
 put1   put    filo1,b0
        skp    loop
 eof    cls    all
        eoj
 @pf2=dateage.subs   # load (at run-time) common subrtns to increment dates

The pf2 parameter file (dateage.subs in this example) may be stored in any of the PFPATH directories provided (/home/uvadm/pf in this case).

The calling job (warmas1 in this case) need not be in any of the PFPATH's For example it might have been called explicitly as follows:


 uvcopy pf2/warmas1       - execute 1 of the date increment jobs
 ==================

 uvcopyxx 'pf2/*'          - execute all uvcopy jobs in the pf2 directory
 ===============            (uvcopyxx is a script provided in ~uvadm/sf)

Goto:   Begin this document End this document UVSI Home-Page

I1. uvcopy INSTRUCTION & OPERAND FORMATS

    opcode   op1start(op1lth),op2start(op2lth)  - instruction format
             receiving-operand <-- sending-operand
    mvc   h0(128),r0          - sample instruction #1
                                move 128 bytes from area 'r' to area 'h'
                                (from an input record area to a work area)
    unp   b100(9),a20(5)      - sample instruction #2
                                unpack bytes 21-25 of area 'a' (in rec?)
                                into bytes 101-109 of area 'b' (out rec?)
    unp  b100(9),a20(5)
         b______               - a letter a-z identifies the op1 area
                                 (always the receiving area)
         _100                  - start bytes are displacements within the area
                                 (the number of bytes preceding the 1st byte)
                                 (or the offset within the area)
             (9)               - the length of the data field
                               - startbyte + length cannot exceed area size
                ,a_____        - op2 area address identified by a letter a-z
    add  b100(9),25            - numeric constant identified by the lack of
                 --              any letter prefix
    mvc  p20(8),'total**'      - character constants enclosed in quotes
               ,c'total**'     - may prefix with a 'c' if desired (default)
    scn  r0(80),x'0a'          - hexadecimal constants identified with 'x'
    mvc   h20(100),r0         - some instructions such as move character
                                do not require op2 length since it is always
                                the same as the output length
    mvn   h50(9za),r20(5pe)   - instructions such as move numeric allow
                                field type codes within the length specs
                              - this example would convert a packed ebcdic
                                field to a zoned ascii field

Goto:   Begin this document End this document UVSI Home-Page

J1. uvcopy $symbols

If desired you may load area 'q' with a table of $symbols & their corresponding addresses - area.displacement(length.type).

The $symbols may then be coded on following instruction operands instead of the actual area.dsp(lth.typ).

sample $symbol 'lod'ing & referencing

 # symbols - uvcopy prmtr file to illustrate $symbols
 #         - input file is customer master to be listed
 fili1=cusmas,rcs=80,typ=RSF
 filo1=cuslist,rcs=80,typ=LSTt
 lod=q0(48)                     # load $symbols in area 'q'
 $cusrec          =a0(80)
 $cusnum          =a0(8)
 $status          =a8(2)
 $name                            =a10(20)
 $adrs                            =a30(20)
 $city                            =a50(20)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #June2009 - field definitions now FREE FORMAT in 48 bytes max (orig 32)
 #         - the '=' of field-def always stored in col 34 for fixed lookup
       opn   all
 loop  get   fili1,$cusrec
       skp>  eof
       cmc   $status,'de'
       skp=  loop
       mvc   p0(8),$cusnum
       mvc   p10(20),$name
       mvc   p32(20),$adrs
       mvc   p54(20),$city
       put   filo1,p0(80)
       skp   loop
 eof   cls   all
       sysv1 'lp $filo1'
       eoj
Note
  • there are also several 'built-in' $symbols for the system
    registers, counters,& accumulators
  • see the work areas documented in uvcopy2.doc for complete details
    but as an example '$rx' could be used for register 'x'
    instead of 'x94(4b)'

Goto:   Begin this document End this document UVSI Home-Page

K0. uvcopy Instruction summary by functional groups


 #01. logical----------> mvc,mvf,mvr,mvp,cat,clr,edt,anc,orc,xor

 #02. arithmetic-------> mvn,add,sub,mpy,div,pac,unp,xft

 #03. comp/test/skip--->  cmc,cmn,skp,nop,tst,tsb,mwb

 #04. sequential I/O--->  opn,cls,get,put,rel,rtb,wtb

 #05. Indexed I/O------>  set,red,wrt,upd,del,lck,ulk

 #06. message&control--> msg,can,eoj,tim,wat,bal,ret,bcr

 #07. translation------>  tra,tre,trl,tru,trt,hxc,chx,vhx

 #08. scan&replace----->  scn,rep,mvu,sct,rpt,sts,rts

 #09. squeeze-insert--->  sqz,sqf,jus,cnt,ins

 #10. conversion------->  fix,var,dlm,und,swp,dat,rfm

 #11. special---------->  sys,lok,pop,fxt,env,evt

 #12. sort------------->  sxo,sxp,sxs,sxg,sxc,srt

 #13. table------------>  tbl,tbf,tbh,tbp,tbd
NOTE
  • This section (uvcopy1.doc) contains instruction summaries only.
  • Please see the detailed formats & rules for each instruction,
    in uvcopy3.doc (part 3 of this uvcopy documentation).

Goto:   Begin this document End this document UVSI Home-Page

K1. grp 1 logical instructions - mvc,mvf,mvr,mvp,cat,clr,edt,anc,orc,x or

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    mvc   operand1,operand2           - move characters
    mvc   area.dsp(lth),area.dsp      - format op1,op2 addresses
                                      - op2 of mvc needs no length since it
                                        is always the same as op1 length
    mvc   area.dsp(lth),'constant'    - format op2 constant
    mvc   b0(80),a0                   - move 1st 80 bytes of area 'a'
                                        to 1st 80 bytes of area 'b'
    mvc   p40(5),'total'              - move the constant 'total'
                                        to bytes 41-45 of area 'p'
    mvf   op1(lth),op2(lth),'fillchar' - move op2 data to the op1 area
                                         & fill any remaining bytes in op1
                                         with the op3 char (default blank)
    mvf   b20(60),a20(30),' '         - move 21-50 of a to 21-50 of b
                                        then fill 51-80 of b with blanks
    mvr   b0(10),a0(8),'0'            - move op2 to op1 right adjusted
                                        left filling with the op3 character
                                        (default is blank)
    cat   b0(80),a0(40)               - concatenate op2 data onto the op1 data
                                        scans back to find last nonblank in op1
    edt   op1adrs,op2adrs,op3mask     - edit op2 data into the op1 area
                                        controlled by the op3 edit mask
    edt   p20(9),a50(6z),'z,zzz.99-'  - edit the 6 bytes of zoned numerics
                                        in 51-56 of 'a' into 21-29 of 'p'
    anc   op1adrs,op2mask             - 'and' character (erase bits)
    anc   h20(8),x'7f'                - erase the x'80' high order bit
                                        from bytes 21-28 of area 'h'
    orc   op1adrs,op2mask             - 'or' character (add bits)
    orc   p0(128),x'20'               - add the x'20' bit to 1st 128 bytes
                                        of area 'p' (make it displayable?)

Goto:   Begin this document End this document UVSI Home-Page

K2. group #2 - arithmetic - mvn,add,sub,mpy,div,pac,unp,xft

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    mvn   op1receiving,op2sending             - move numeric
    mvn   area.dsp(lth.typ),area.dsp(lth.typ) - format
    mvn   b90(8ze),a20(pa)         - move 21-25 of area a (packed ASCII)
                                     to 91-98 of area b (zoned EBCDIC)
    mvn   x0(4b),c10(7za)          - move (convert) 11-17 of c (zoned ASCII)
                                     to 1-4 of area x (system register 'a')
                                     (registers are always 4 bytes binary)
    mvn   $ra,c10(7)               - same as above using $symbol for rgstr a
                                     & defaulting data type to zoned ascii
    add   op1adrs,op2adrs          - add the contents of op2 to the contents
                                     of op1 & store result in op1
    add   op1adrs,op2numcon        - (alternate format - op2 numeric constant)
    add   b20(5p),a90(8z)          - add 91-98 of a (zoned) to 21-25 of b
                                     (packed) & store result in op1 (packed)
    add   $rb,5                    - add 5 to register 'b'
                                   - $rb could also be coded as x4(4b)
    sub   b28(8),b20(8)            - subtract 21-28 of b from 29-36 of b
                                     & store result in 29-36 of b
                                     (data type 'zoned ascii' by default)
    mpy   b80(8),a20(5p)          - multiply 81-88 (zoned) of area b by 21-25
                                    of area a (packed) & store result in op1
    div   h100(4b),2              - divide 101-104 of area 'h' (binary) by 2
                                    & replace op1 with the result
    pac   b20(5),a80(9)           - pack bytes 81-89 of area a
                                    into bytes 21-25 of area b
    unp   o80(9),i20(5)           - unpack bytes 21-25 of area 'i'
                                    into bytes 81-89 of area 'o'
    xft   b0(9),a20(5p),12       - crossfoot the 12 x 5 byte packed fields
                                   in 21-80 of area a into bytes 1-9
                                   of area b (zoned by default)

Goto:   Begin this document End this document UVSI Home-Page

K3. group #3 - compare/test/skip - cmc,cmn,skp,nop,tst,tsb,mwb

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    cmc   area.dsp(lth),area.dsp      - compare characters
    cmc   area.dsp(lth),'constant'    - op2 may be adrs or constant
    cmc   a0(2),'m2'                  - compare cols 1&2 of area m to 'm2'
    skp=  mstr                          & skip to label 'mstr' if equal
 mstr nop                             - label or tag can be coded in col1+
                                        of any other instruction (max 8 chars)
                                      - may code on a 'nop' instruction
                                        (no-operation) if desired
    cmc   b2(6),c0                    - compare 3-8 of 'b' to 1-6 of 'c'
    skp!  1                             & skip 1 instruction if unequal
    cmn   area(lth.typ),area(lth.typ) - compare numeric
                                      - converts data types as required
    cmn   area(lth.typ),numeric-const - op2 may be adrs or numeric constant
    cmn   a20(5p),25                  - compare 21-25 of area 'a' (packed)
    skp>  2                             to 25 & skip 2 instrns if >
    tst   m8(1),'abcde'               - test col 9 of area 'm' for a,b,c,d,e
    skp=  1                             & skip next instrn if any match
    tst   m10(10),'abcdefghi'         - test cols 11-20 of m for any/all a-i
    skp=  allok                         cc set '=' if all columns match in op2
    skp>  someok                        cc set '>' if some but not all match
    skp<  noneok                        cc set '<' if no columns match op2 chars
    tsb   c24(1),x'01'                - test col 25 of area 'c' for a 1 bit
    skp=  bit1                          & skip to label 'bit1' if present
    mwb   area(lth),'tag1=val1,tag2=val2,tag3=val3,etc...'
                                       - multi-way-branch
    mwb   b0(1),'typ1=1,typ2=2,typx=x' - tests col1 of area b to 1,2,or 3
                                         & branches to the matching label
    ---                                  or falls thru if no match

Goto:   Begin this document End this document UVSI Home-Page

K4. group #4 sequential I/O - opn,cls,get,put,rel,rtb,wtb

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    opn   fili1                    - open a file
    opn   all                      - open all files declared
    cls   fili1                    - close a file
    cls   all                      - close all files declared
                                     (performed automatically by 'eoj')
    get   fili_,area.dsp(lth)      - get a record
    get   fili1,a0(80)             - get an 80 byte record from fili1
    skp>  eof                        into area 'a' & set cc > if EOF
    put   filo1,b0(80)             - write an 80 byte record to filo1
                                     (sequential output file)
    rel_  filr_,record#/byte#      - set relative record# or byte# in a
                                     UNIX (or MSDOS) system file
    relr  filr1,50                 - set file pointer to record #50 in filr1
    relb  filr2,$ra                - set ptr to the byte# held in rgstr 'a'

Goto:   Begin this document End this document UVSI Home-Page

K4a. group #4 sequential I/O - opn,cls,get,put,rel,rtb,wtb (continued)

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    rtb   file,area(lth),area(lth) - read a file into a work area, probably
                                     intended for use as a lookup table
    rtb   fili2,m0(20),m0(20)      - read fili2 & store 20 bytes of each record
                                     in area 'm' (until EOF or '~~' col 1&2)
    skp>  err                      - cc set > if file too big for the area

wtb file,area(lth),area(lth) - write a data table out to a file

    wtb   fili2,m0(20),m0(20)      - write out data from area 'm' to filo2
                                     20 bytes per record until end of area
                                     or entry reached with '~~' in cols 1&2
                                     or a null x'00' in 1st 2 bytes

Goto:   Begin this document End this document UVSI Home-Page

K5. group #5 Indexed I/O - red,wrt,upd,del,set,lck,ulk

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    clr   c0(200),' '              - clear record area
    mvc   c60(5),'SMITH'           - store key in record area
    setm7k2 filr1,c0(200)          - set key #2 => 'SMITH'
    red?  filr_,area(lth)          - read a record from an ISAM keyed file
                                     (key must be pre-stored in the I/O area)
    mvc   c0(6),'123456'           - store key of record desired
    red=  filr1,c0(200)            - read the record whose 1st key = '123456'
    skp=  found                      & set condition-code '=' if found
                              note - see complete explanation in the detailed
                                     instruction guide further below
    upd   filr1,c0(200)            - update a record in an ISAM file
                                     whose key & data was stored in op2 area
    skp<  nofind                   - cc set '<' if record key not found
    wrt   filr1,c0(200)            - write a new record in an ISAM file
                                     whose key & data was stored in op2 area
    skp<  dup                      - cc set '<' if record key already exists
    del   filr1,c0(200)            - delete a record in an ISAM file
                                     whose key & data was stored in op2 area
    skp<  nofind                   - cc set '<' if record key not found
    mvc   r20(6),'SMITH'           - store key value for 'set' instruction
    set=>k2  filr1,r0(256)         - select key#2 & set file pointer to 1st
    skp=  found                      record whose key2 = or > 'SMITH'
    skp<  nofind
    skp>  eof
    lck   fili1                   - lock a DISAM file
    lck   filr1                     (for input or random files)
                                  - must have specified typ=ISFl2
                                    (see file typ options)
    ulk   fili1                   - unlock a DISAM input/random file

Goto:   Begin this document End this document UVSI Home-Page

K6. group #6 - message&control - msg,can,eoj,tim,wat,bal,ret,bcr

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    msg   'hello world'          - display data on standard output (screen)
                                 - op1 may be a constant
    msg   area.dsp(lth)            or any area
    msg   op1,op2                - will also display op2 if present
    msg   'bad date',a20(8)      - useful to display an errmsg + data area
    msgl2 'bad record',b0(80)    - option 'l2' will display op2 on 2nd line
                                   or double space if no op2 present

can 'error message data' - cancel the program with an error msg

    eoj   [exit-code]            - end the job
                                 - automatically closes all open files
    eoj   99                     - optionally op1 may specify an exit code
    tim   ---                      - get current system date & time
                                     into bytes special work storages
                                   - $date2  = ccyymmddhhmmss
                                     $time2  = seconds since 1970 (binary)
                                   - 'tim' requires no operands
    wat   op1area(lth.typ)         - wait the no of seconds specified by op1
    wat   a20(5p)                  - wait the no of seconds contained in the
                                     5 byte field in cols 21-25 of area 'a'
    wat   $rc                      - wait the no of seconds held in rgstr 'c'
    wat   x8(4b)                   - same as above, $rc is the $symbol for
                                     rgstr c located in bytes 9-12 of 'x'
    bal   subrtn                   - branch & link to a subroutine
                                   - may be nested 10 deep
                                   - label may be 8 chars max
      bal   subx                   - branch & link to subrtn 'subx'
 subx ---
      ---
      ret                          - return from subroutine
                                   - no operands required

Goto:   Begin this document End this document UVSI Home-Page

K7. group #7 - translation - tra,tre,trl,tru,trt,hxc,chx,vhx

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    tra   op1area(lth)         - translate to ASCII (from EBCDIC)
    tra   b0(80)               - translate 1st 80 bytes of area b to ASCII
    tre   op1area(lth)         - translate to EBCDIC (from ASCII)
    tre   b0(80)               - translate 1st 80 bytes of area b to EBCDIC
    trl   op1area(lth)         - translate to lower case (from UPPER case)
    trl   c0(80)               - translate 1st 80 bytes of area c to lower
    trlq1 c0(80)               - option q1 inhibits translation in single quotes
    trlq2 c0(80)               - option q2 inhibits translate in double quotes
    tru   op1area(lth)         - translate to UPPER case (from lower case)
    tru   c0(80)               - translate 1st 80 bytes of area c to UPPER
    truq3 c0(80)               - inhibit translation within single&double quotes
    clr   $trt(32),' '         - modify the supplied neutral translate table
                                 (would clear control codes to blanks)
    trt   b0(80),$trt          - translate area b via modified trt table
    hxc   op1(2*lth),op2(lth)  - convert data to hex-character representation
                               - op1 output length will be twice op2 input lth
                                 (op2 length need not be specified)
    hxc   b0(80),a0            - convert 1st 40 bytes of area 'a' to hex-char
                                 representation in 1st 80 bytes of area b
    chx   op1(lth),op2(2*lth)  - convert hex-char representation to true data
                               - op1 output length will be 1/2 op2 input lth
                                 (op2 length need not be specified)
    hxc   b0(40),a0            - convert hex-character representation
                                 in 1st 40 bytes of area 'a' to true data
                                 in 1st 80 bytes of area 'b'
    vhx   b0(80),c0(80),d0(80),a0(80)
                               - convert op4 data to vertical hex representation
                                 op1=printable chars, op2=zones, op3=digits

Goto:   Begin this document End this document UVSI Home-Page

K8. group #8 - scan/replace - scn,rep,mvu,sct,rpt,sts,rts

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

scn op1area(lth),op2pattern - scan op1 area for op2 pattern

    scn   h0(128),'RR#'             - scan 128 bytes of 'h' for 'RR#'
    skp=  rr                          & skip to label 'rr' if found
                                    - also sets index rgstr 'x' to the
                                      displacement of the found pattern
    scnrp b0(80),'!'                - scan 1-80 of area b from the right
                                      searching for the 1st non-blank
                                      option 'r' scan right to left
                                      option 'p' pattern match !=nonblank
    rep   op1area,op2search,op3replace - scan op1 area for the op2 pattern
                                      & replace all occurrences with op3
    rep   h0(128),'AS400','UNIX'    - scan for 'AS400' & replace with 'UNIX'
    skp=  found                     - cc set = if at least 1 replacement made
    mvu   op1area,op2data,op3search - move op2 data to the op1 area until
                                      the op3 search pattern is found
                                      (or until the end of op1 is reached)
    mvu   b20(60),a20,','           - move 'a' to 'b' starting in column 21
                                      until a comma is found or column 80
    skp=  found                     - cc set = if a comma was found & rgstr
                                      x will hold the no of cols moved

Goto:   Begin this document End this document UVSI Home-Page

K8a. group #8 - (continued) - scn,rep,mvu,sct,rpt,sts,rts (continued)

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

sct - scan & replace by table

    sct   area(lth),tablebase(entrylth),patternoffset(patternlth)
                           - scan op1 data for op2 table matches
                             set cc = if any match found in table
    sct   a20(80),k0(10),k0(10)
    skp=  match
                           - scan cols 21-100 of area a for any of the
                             patterns in the table in area k
                             (each entry 10 bytes max ended by 1st tilde)
                           - table was probably loaded by the 'lod' function
 lod  k0(10)              - load table of patterns for the 'sct' instruction
 MR.~~~~~~~
 MRs.~~~~~~
 DR.~~~~~~~
 ~~~~~~~~~~
    rpt   datarea(lth),tablebase(entrylth),patternoffset(patternlth)
                           - scan op1 data for op2 table matches
                             replace data if match found in table
    rpt   a20(80),h0(20),h0(10)
    skp=  hit1
                           - scan cols 21-100 of area a for any of the
                             patterns on the left side of the table in area h
                           - each entry 20 bytes, left & right sides 10 each
                             search pattern & replacement data ended by '~~'
                           - condition code set = if any replacement made
 lod  h0(20)               - load table of patterns for the 'rpt' instruction
 Mister~~~~Mr.~~~~~~~
 Madam ~~~~Ms. ~~~~~~
 Doctor ~~~Dr. ~~~~~~
 ~~~~~~~~~~~~~~~~~~~~
    sts   b0(100),b7(65),'ACCEPT'  - search a specified portion of a table
    skp=  match                      in memory for a specified pattern
    rts   b0(100),b7(65),'SYSWCH','SWITCH'
                  - search/replace a specified portion of a table in memory
                  - table must be terminated by an entry with '~~' in 1-2

Goto:   Begin this document End this document UVSI Home-Page

K9. group #9 - sqz,sqf,jus,cnt,ins

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    sqz   op1area,op2char           - squeeze out occurrences of the op2
                                      character from the op1 area
    sqz   op1area,'1char'           - op2 is usually a 1 character constant
    sqz   b0(80),' '                - squeeze out all blanks from between words
                                      in the 1st 80 bytes of area b
    sqzc1 b0(80),' '                - squeeze multiple blanks to 1 blank
    sqzc2 b0(80),' '                - would adjust the no of blanks between
                                      words to 2 (squeezing or inserting)
    sqzc1l2 b0(80),' '              - squeeze multiple blanks to 1 blank
                                      & also leave 2 blanks on the left side
                                      of op1 (default is none)
    sqza  b20(80),','               - squeeze out 'all' commas in 21-100 of b
    sqf   op1area,nn,'pattern'       - squeeze fields
    sqf   b0(20),5,' '               - area b contains 5 x 20 byte fields
                                     - any all blank fields will be squeezed
                                       ie - data fields shifted left leaving
                                            any blank fields on the right
    jus   area(lth),delchar,fillchar - [left] justify data in the op1 area
                                     - remove blanks on left & add on right
    jus   b20(10),' ',' '            - left justify data in cols 21-30 of b
    jusr  b20(10),' ','0'            - right justify cols 21-30 of area b
                                       remove blanks on right
                                       & fill zeros on left
    cnt   op1area,'pattern'          - count no of op2 patterns in op1 area
    skp=  found                        cc set = if 1 or more finds
    cmn   $ci1,9                      - actual no of occurrences stored in
    skp>  toomany                      instruction counter #1
                                     - also counts various types of chars in
                                       ctrs 2-10 (alpha,lower,upper,etc)
    ins   b10(30),'19'               - insert '19' in cols 11-12 & shift
                                       remainder over 2 columns

Goto:   Begin this document End this document UVSI Home-Page

K10. group #10 - conversion - fix,var,dlm,und,swp,rfm,dat

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    fix   op1area,op2data,nn,'sep'   - convert the nn variable lth fields
                                       in op2 (separated by op4 pattern)
                                       to fixed lth fields in op1
    fix   b0(20),a0(100),5,','       - area 'a' consists of 5 variable lth
                                       fields separated by commas
                                     - will be converted to 5 fixed lth
                                       20 byte fields in area 'b'
                                       (each blank padded on the right)
    var   op1area,op2data,nn,'sep'   - convert the nn fixed lth fields in op2
                                       to variable lth fields in op1 by
                                       removing trailing blanks in each field
                                       & inserting the op4 separator pattern
    var   b0(100),a0(20),5,','       - convert the 5 fixed 20 byte fields in 'a'
                                       to variable lth fields in area 'b'
                                       replacing trailing blanks with a comma
    swp   op1area(lth),'sep'         - swap left & right sides of op1
                                       based on the op2 separator character
    swp   b20(30),','                - swap left & right sides of 21-50 of 'b'
                                       if we find a comma (else no change)
                                       for example:  Townsend, Owen
                                           becomes:  Owen Townsend

Goto:   Begin this document End this document UVSI Home-Page

K10a. group #10 (continued) - conversion - fix,var,dlm,und,swp,rfm,dat

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    rfm   op1area,op2data,nn,'mask'  - reformat the nn data fields in op2 into
                                       the op1 area guided by the op4 mask
    rfm   b20(3),a20(2),10,x'10102c' - reformat 10x2 byte fields in 21-40 of 'a'
                                       into 10x3 byte fields in 21-50 of 'b'
                                     - example: aabbccddeeffgghhiijj
                                       becomes: aa,bb,cc,dd,ee,ff,gg,hh,ii,jj
                                     - x'10' in the mask copies a data character
                                       anything else inserted (x'2c' is comma)
    dat____ op1area(lth),op2data(lth)  - date conversion
                                       - depending on options
    datcj       - calendar to julian             ccyymmdd  to   ccyyjjj
    datcn       - calendar to days-since-1900    ccyymmdd  to     nnnnn
    datjc       - julian to calendar              ccyyjjj  to  ccyymmdd
    datjn       - julian to days-since-1900       ccyyjjj  to     nnnnn
    datnc       - days-since-1900 to calendar       nnnnn  to  ccyymmdd
    datnj       - days-since-1900 to julian         nnnnn  to   ccyyjjj
    datcj     b20(7),y0(8)        - convert current system date
                                    (provided by uvcopy in area y ccyymmdd)
                                  - to julian ccyyjjj in bytes 21-27 of 'b'

Goto:   Begin this document End this document UVSI Home-Page

K11. group #11 - special - sys,lok,pop,fxt,env,evt

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

    sys   'system command'          - pass system commands to the
                                      UNIX operating system
    sysv1 'lp $filo1'               - pass the spool command to UNIX OS
                                      to print a file
                                    - probably at  eoj (1st cls the file)
    lok   op1table,op2argument      - lookup a table of data (op1)
                                      via an argument (op2)
    lok   b0(20),a10(2)             - lookup the table of 20 byte entries
                                      in area 'b' using the 2 byte argument
                                      in cols 11-12 of area 'a'
                               note - see the 'lod' function documented
                                      previously which is usually used to
                                      load the data table
    pop   op1dsp(lth)               - process user option string
                                    - sort&convert option string op1 into
                                      process option storage in area 'x'
                                      (see work area x layout)
    fxt   op1area(lth)             - add a uvcopy instruction to the
                                     end of the execution table
    env   b0(100),'PATH'           - get any environmental variable
    evt   b0(8000),80              - get & table all env vars
                                   - op1 lth defines max area for table
                                   - op2 defines length of each entry

Goto:   Begin this document End this document UVSI Home-Page

K12. group #12 - sort instructions - sxo,sxp,sxs,sxg,sxc & srt

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

external (file) sort: sxo,sxp,sxs,sxg,sxc

sxo rcsz,'isk1,isk2,etc','sortwork dir' - open the sort

    sxo   256,'228(dp3),59(15),0(8)','tmp'     - open sort for 3 keys
                                             1 - 229:231 descending packed
                                             2 - 60:74 ascending character
                                             3 - 1-8 ascend char (default)
    sxp   a0(256)                   - put record to the sort
    sxs                             - perform the sort
    sxg                             - get a record from the sort
    skp>  eof                       - cc set > at end of all records
    sxc                             - close the sort
                                    - not required unless you want to do
                                      2 sorts in 1 job

internal (table) sort: 'srt'

    srt   op1area(lth),nnn         - sort the nnn items of data in the op1
                                     area each of op1 lth bytes long
    srt   b20(2),10                - sort the 10x2 byte fields in 21-40 of 'b'
                                     into ascending order

Goto:   Begin this document End this document UVSI Home-Page

K13. group 13 (table) - tbl, tbf, tbh, tbp, tbd

NOTE - this is a CONCISE INSTRUCTION SUMMARY only, please see the complete details & instruction rules in part 3 of this uvcopy documentation.

'table' - build tables in memory to be dumped at end of job

tbl
  • build tables in memory (probably executed for each detail record)
tbf
  • declare format for print editing when written to output file
tbh
  • declare table field headings to be used when edited to output file
tbp
  • print (edit) table(s) to output file (probably at end of job)
tbd
  • dump (unedited) table(s) to output file (probably at end of job)

'tbl' will build tables in memory to be printed at the end of the job. There is no limit on the number of tables or on the number of entries in any 1 table (other than available system memory).

Each table may have an argument up to 32 bytes which could be composed in a work area from several subfields before the 'tbl' instruction is executed. Up to 6 accumulators may be specified for each table.

An entry count is provided automatically so you don't have to waste 1 of the 6 accumulators for this purpose.

Percentages of the 100% total at the bottom, may be automatically calculated, for the entry count & for each of the 6 accumulators.

Several 'tbl' instructions could be executed for each record of the input file, with several different arguments & accumulators. The tables are built & dumped in sequence by their argument fields.

The tables are normally dumped to an output file at the end of the job by the 'tbp' &/or 'tbd' instructions. 'tbp' edits (prints) the tbl entries into a file which may be subsequently printed via 'lp'. 'tbd' writes the the tbl entries (unedited) into a file for additional processing, collection,or storage.

An example of each instruction follows, but this is only an overview in uvcopy1.doc. Please see the 14 pages of documentation in the detailed instruction reference manual uvcopy3.doc.

tblt1f2 a20(16),'city-name;sales;costs;profit',a40(8z),a48(6p),a54(4b) tbff2 p18(20),'zzzzz,zzz.zz-%%%.%%- zzzzz,zzz.zz-%%%.%%- ...etc...' tbhh1 'city name;sales;costs;profit' tbpt1e3 filo1,'sales analysis' tbdt1e3 filo2,'19940430'

Goto:   Begin this document End this document UVSI Home-Page

Visitor Counters for ThisYear and LastYear