* CICSEDTS DOC * ----------------------------------------------- 10/08/93

            Transaction EDTS, to edit Temporary Storage queues

---------------------------------------------------------------- Rel. 1.1




1)                        I N T R O D U C T I O N


    'EDTS' is a CICS transaction that allow to view or update Temporary
Storage queues in CICS, with an operating use similar to a simple full
screen editor, in which every line is a record of the file.
Temporary Storage queue are temporary files specific of CICS environment,
used by applications to store work data, with a file structure similar
to a direct access file, that is a file that can be accessed sequentially
or by record number.

Things you can do with EDTS are:
- normal or hexadecimal view, one record or 20 records in a screen
- string search forward or backward, over all the file o over only a 
  field 
- delete or duplicate of one or more records
- record update in normal or hexadecimal mode
- change of record length
- copy of one or more records in a buffer
- add of one or more records from an previously edited buffer
- create a new Temporary Storage file or delete an old TS file or copy
  into another with another name
- force read-only access


    EDTS is subsidiary to VSAM transaction that is a Vsam file editor in
CICS; nevertheless EDTS can be used independently, as an extension of
system transaction CEBR; actually this IBM utility allow only a view or
a whole delete of a Temporary Storage queue.




2)                         D E S C R I P T I O N


    EDTS can be recalled in a CICS session as a command, in this way:

    EDTS queue-name

where 'queue-name' is a name of eight characters maximum of wanted TS queue.
If this file exist and has at least one record, a screen appear with
a display of the first 20 records.

Let's schematize the screen in this manner:


    /------------------------------------------------------------------+
    ! * EDTS * Temporary Storage queues Editor  -  queuename 12  32  A !
    !     0....+....!....+....!....+....!....+....!....+....!....+     !
    ! ---- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa              !
    ! ---- bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb              !
    ! ---- cccccccccccccccccccccccccccccccccccccccccccccc              !
    ! ---- dddddddddddddddddddddddddddddddddddddddddddddd              !
    ! ---- eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee              !
    ! ---- records ...................................                 !
    ! ---- records ...................................                 !
    ! ---- hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh              !
    ! ---- iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii              !
    ! ---- llllllllllllllllllllllllllllllllllllllllllllll              !
    ! ----                                                             !
    ! ==> _                                                            !
    ! 1=Help 2=Hex 3=Quit 4=Left 5=Right 6=LRec 7=Ba 8=Fo 9=Top 10=Bot !
    +------------------------------------------------------------------/


    Screen is compound by:
- first row, containing TS queue name, number of the first and last records
  displayed on the screen and moving direction, that can be 'A' for
  forward or 'I' for backward.
- second row, with the ruler, in which the number on the left is the start
  display position (the offset) concerning column 1
- rows from 3 to 22, arranged by 'prefix area' (column with '----' on the
  left) on with you can write commands regarding beside record, and
  record itself, displayed normally or in hexadecimal; every record is a
  writable field that can be directly changed by the user; when <Enter>
  is pressed, changes are immediately recorded on the TS queue.
- row 23, the 'command line' on which you can write other commands
- row 24, with a help about use of Function keys



    In 'prefix area', near to the record on which you want to take effect,
you can write these commands:

'/'  : the record become the first record of the screen
'C'  : copy the record in the actual program buffer
       This command can be used also in form 'C n' where n is the number
       of records to copy, from the selected record.
       This program buffer is in turn a Temporary Storage queue with a
       name (if is not changed by its command) is compound by 'EDTS' (for
       the first four characters) and by the terminal name of the user.
'D'  : delete the record from file;
       command can be used also in the form 'D n' where n is the number
       of records to delete, from the selected record.
'F'  : copy the records that are in buffer inside the TS queue, after
       (Following) the actual record; buffer is purged after this insert
'P'  : copy the records that are in buffer inside the TS queue, before
       (Preceding) the actual record;  buffer is purged after insert
'G'  : copy the records that are in buffer inside the TS queue, after
       the actual record; buffer is not deleted after insert, so 'G' can
       be used to insert more times the same records in different points
'"'  : duplicate a record; quotation mark can be followed by a number n
       to duplicate the record n times; note that character 'R' is a
       synonym of quotation mark (")
'<n' : shift left the record of n columns; the first n bytes are lost,
       at the right of the record are added binary zeroes and the record
       length is unchanged; if omit n, default is 1
'>n' : shift right the record of n columns; the first n bytes become
       binary zeroes, record length is unchanged and last n bytes are lost
'A'  : insert a empty record (that is a record full of blanks and with 
       length 80) after the specified record; character 'A' can be followed
       by a number n to insert n empty records; note that letter 'I' is
       a synonym of letter 'A'
'U'  : translate in uppercase the record; if record is very long, are
       translated only first 256 characters;
       command can be written also in form 'U n' where n is number of 
       records to translate in uppercase from actual record
'.n' : put a label corresponding to actual record; near the point (.)
       you put a digit (only one) from 1 to 9; to go to labeled record
       in every moment you can write '.n' in command line, with n
       corresponding to the wanted digit.



    Many of these commands can take effect over a block of records instead
of only one: to do this you double the character and put it near the first
and near the last record of the block.

'CC'  : copy in buffer; you cannot use multiplier 'n' near 'CC'
'""'  : double the block; you cannot use multiplier 'n' near quotation
        mark; 'RR' is the synonym
'DD'  : delete the block
'<<n' : shift left the block of n columns
'>>n' : shift right the block of records of n columns
        note that round brackets '(' and ')' are synonyms of '<' and '>'
'UU'  : translate a block of records in uppercase


     When you repeat Copy command, records are added to the same buffer,
until buffer is explicitly deleted with command 'PURGE'. Buffer can
in turn be edited with command 'EDTS', as we see later.


    Command line commands are partially a duplicate of PF keys:

    Help     (PF1) : recall Help screen , with a summary of all commands
    Hex On/Off(PF2): change display mode in hexadecimal (On) or return in
                     normal mode (Off) removing hexadecimal view
    Quit     (PF3) : end the program; this command has 'File' like synonym
                     note that 'Quit' don't work to abandon updates done
                     (like in VSAM utility): every update is always recorded
                     when the user press <Enter> on the terminal; there isn't
                     any way to backout updates done in a Temporary Storage
                     queue automatically.
    Forward  (PF8) : go forward of a screen (that is 20 records); in command
                     line can be specified the number of pages
    Backward (PF7) : go backward of a screen; in command line you can specify
                     the number of page beside 'Backward'
    Right    (PF5) : shift view at right and allow to display records grater
                     then a screen; shift is 40 character if you are in normal
                     view or 20 if you are in hexadecimal view. In command
                     line beside command you can specify number of columns
                     to shift: this number is always truncated by program to a
                     multiple of 10.
    Left     (PF4) : shift view left, with use similar to 'Right'
             (PF6) : display in prefix area every record length; with this
                     view you can change the length for every record you want;
                     a change like this produce a record trunk or a right
                     padding with blanks.
    Top      (PF9) : go to start of file
    Bottom   (PF10): go to end of file



    Let's describe now remaining commands:

    Zoom   : change view mode from 20 records in a screen to only a record,
             with these benefits:
             . record is displayed at the same time in characters and in
               hexadecimal
             . in this view mode program supports records longer than 2000
               bytes

             Screen has this look:



    /------------------------------------------------------------------+
    ! * EDTS * Editor of Temporary Storage queues - queuename 12 --  A !
    !                                                                  !
    ! ---- 1 . . .  + . . .  ! . . .  + . . .        ....+....!....+...!
    ! 0000 aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa     0 AAAAAAAAAAAAAAAAAA!
    ! 0014 bbbbbbbb bbbbbbbb bbbbbbbb bbbbbbbb    20 BBBBBBBBBBBBBBBBBB!
    ! 0028 cccccccc cccccccc cccccccc cccccccc    40 CCCCCCCCCCCCCCCCCC!
    ! 003C dddddddd dddddddd dddddddd dddddddd    60 DDDDDDDDDDDDDDDDDD!
    ! 0050 eeeeeeee eeeeeeee eeeeeeee eeeeeeee    80 EEEEEEEEEEEEEEEEEE!
    !                                                                  !
    !                                                                  !
    !                                                                  !
    !                                                                  !
    ! ==> _                                                            !
    ! 1=Help 2=Hex 3=Quit 4=Left 5=Right 6=LRec 7=Ba 8=Fo 9=Top 10=Bot !
    +------------------------------------------------------------------/


    In the left of the screen record is displayed in hexadecimal with
    offset (still in hexadecimal) as for start of the record; on the right
    record is in characters, with a decimal offset. Every line display
    20 characters of the record; a full screen can contain 360 bytes.
    Can be edited both record in hexadecimal and in characters: also in
    this mode record is rewritten immediately in TS queue.
    Prefix area exist even here: is field '----' on the left of the ruler;
    its function is unchanged and can be used to write the same commands 
    as before.
    In command line you can use the same commands as before; the same for
    function keys, that have these changes:
    PF7 / PF8 go backward / forward inside the same record, if this is
              longer than a screen; go to the preceding / following record
              if it is contained in a screen or if view is at the start /
              end of a long record. (The same for commands 'Backward n'
              and 'Forward n')
    PF2  no effect
    Changing record, for example with +/-n in command line, offset is
              unchanged

    To return in normal view mode you will write 'Zoom' again in command
    line.



    Key n  : Direct skip to a record.
             n is ordinal number of the record as for start of file

    +/-n   : relative skip of 'n' records forward (+) or backward (-);
             (plus sign can be omitted)

    EDTS   : self recall to view or change buffer records.
             Beside command EDTS can be specified a TS queue name, if you
             don't want edit default buffer queue but another queue;
             anyway, as long as you don't change buffer name, commands 
             as 'Get' will use only default queue.

    Purge  : delete buffer queue, that is the TS queue used as buffer.
             Note that this buffer queue is always deleted when you exit
             the program; to avoid this, you must rename the buffer queue
             with command 'Buffer' before program end.

    Buffer TS-queue-name: change the name of the TS queue that is the buffer;
             commands like 'Get' or 'C' in prefix area from this moment
             will read or copy from or to this new TS queue.

    Zone col1 col2 : define a field that start from specified first column
             'col1' and end to the second 'col2' (see characters '<' and '>' 
             on the ruler). This definition restrict the search when you
             use command '/.../'.
             By default, search is on a full record.

    /string/ : search the specified string
             If a preceding 'Zone' command has been specified, the search
             is on the selected field, otherwise on the full record.
             Found records are highlighted with an arrow '===>' in prefix
             area; if no string is found, search end at the end of file.
             If you write this command in hexadecimal mode, string enclosed
             between slashes must be written in hexadecimal. Second slash
             to close the string is mandatory. If you want search a string
             with just a slash inside, then string (and slash) must be
             written in hexadecimal to avoid ambiguities.
             Search direction depend by actual direction displayed on top
             right of the screen: with 'A' direction is forward whereas with
             'I' direction is backward.
             Remember that search is case sensitive: if terminal or CICS
             don't translate what you write, if a string between slashes
             is in lowercase this is what is exactly searched.

    Find   : previous string search is continued in the actual direction.

    .n     : go to record previously labeled with '.n' in prefix area;
             'n' can be one digit from 1 to 9.

    Reset  : delete all labels previously stored.


     Is possible to recall other utility programs from EDTS:

     Sort col1 col2 : program CICSSORT is recalled and actual TS queue
             is sorted in ascending order and output is put in the TS
             queue actually defined as buffer in EDTS; sort field is 
             unique and is defined with start and end column.
     Submit  : submit to internal Reader actual editing queue, that must
             be a valid JOB. This submission is done recalling program
             CICSSUB.


    Note: all commands in command line can be shorted up to one letter
provided that there aren't ambiguities with other commands; for example:
F  = Forward  ;   FI = Find   ;   FIL = File

    During record delete in TS queue happens that at the end of file there
are spurious records in number equal to deleted records; this is due to
CICS that don't allow a single deleted record in TS queues (but only a
delete of an entire queue). 'Phantom' records at the end of file are long
one byte of value '00'; VSAM transaction (and EDTS itself) ignores this
records, that so don't bring any problem. To eliminate this spurious
records you can copy this TS queue to another queue (see COPY option later).



    Let's describe now a complete syntax of EDTS transaction, explaining
the use of optional parameters:


                      +                     +
                      ! NEW / ADD  numrec   !
    EDTS queue-name   ! COPY / MOVE TSname2 !
                      ! ERASE / DELETE      !
                      + RO                  +

    None of these parameters are essential; its use can be useful in some
situations.

NEW and ADD are synonyms; because is not possible to a new queue (that is
        a not existent queue) with parameter ADD or NEW program before write
        a record in this new queue (that is a blank record 80 bytes long),
        than go in edit mode. This record obviously can be deleted later.
        Right to NEW or ADD you can specify how much blank records you
        want.

COPY and MOVE are similar; TS queue is copied in a new queue; in this copy
        spurious records are deleted, that is records containing only a
        binary zero byte.

ERASE and DELETE are synonyms; TS queue is deleted.

RO   :  TS queue is accessed in Read-Only








5)                     I N S T A L L A T I O N


    Program is a single executable named CICSEDTS.
An entry in PCT CICS table for transid 'EDTS' and an entry in PPT for 
program 'CICSEDTS' will be created. Transid can be changed as you like
as the program name; however consider that the program name is changed
transaction cannot recall itself with command 'EDTS'.
    Program is written in Assembler Command Level, in conversational mode;
run from CICS 3.1 forward, has been tested also in CICS Version 4.1.
A VSE/CICS version is available.


Examples of table coding:

PCT :
         DFHPCT   TYPE=ENTRY,
               TRANSID=EDTS,
               PROGRAM=CICSEDTS,RSL=PUBLIC


PPT :
         DFHPPT   TYPE=ENTRY,PROGRAM=CICSEDTS,RSL=PUBLIC


    The only important thing is define the language as Assembler (that
is the default in traditional tables, but not in CEDA).


    Program could be recalled from another program with a EXEC CICS LINK,
passing parameters in COMMAREA, instead of to be recalled by user.
COMMAREA can be of any length up to 100 bytes maximum. In practice, if we
ignore optional parameters, in COMMAREA will be passed only the name
of the TS queue to edit, so the length can be 8 bytes without worry.


    Program has these limits:
- CICS terminal must be a standard 3270  80x24



