z390 ASSIST Support

• z390 ASSIST instructions
  • XDECI   RX X'53rxbddd' r1.s2 convert decimal to binary
    • Start scan for next decimal number at s2 skipping leading blanks
    • Convert decimal number to binary in r1 until non decimal character found
    • Set register 1 to address of the last non decimal character found
    • Set condition code 0 if number converted successfully else set condition code 3
  • XDECO RX X'52rxbddd' r1,s2 convert binary to decimal
    • Convert binary 32 bit r1 value to right justified 12 character decimal field at s2
  • XDUMP RXSS X'E06xbdddbddd' s1(x1),s2 - dump registers and/or storage
    • If no operands are specified, dump registers and the default storage area
      • If no XLIMD instruction has reset default storage dump area, dump all storage
    • if s1(x1) address of storage area and s2 length of area are specified just dump that area
  • XGET     RXSS X'E0Axbdddbddd' s1(x1),s2 read record from ASCII file DDNAME=XGET into area s1(x1) with length of s2
  • XHEXI   RX X'61' r1,s2 convert hex to binary (cc3 if no hex, update field addr)
  • XHEXO RX X'62' r1,s2 convert binary to hex (12 bytes, update field addr)
  • XLIMD RXSS X'E08xrbdddbddd' s1(x1),s2 set default XDUMP storage area address and length
  • XPNCH RXSS X'E04xbdddbddd' s1(x1),s2 write to DDNAME=XPNCH with length s2
  • XPRNT RXSS X'E02xbdddbddd' s1(x1),s2 write to DDNAME=XPRNT with length s2
  • XPUT    RXSS  X'E0Cxbdddbddd' s1(x1),s2 write to DDNAME=XPUT for length s2
  • XREAD RXSS X'E00xbdddbddd' s1(x1),s2 read record from DDNAME=XREAD for length s2
• z390 ASSIST command can be used to assemble, link, and execute assist programs
  • Use the command ASSIST filename where filename is the base name of any mainframe assembler source program with file type MLC to assemble, link, and execute the program on Windows XP/Vista or Linux system using z390 GUI or command line interface.  This command sets the ASSIST option  and defines the following environment variables for input and output ASCII text files:
    • XREAD=filename.XRD
    • XPRNT=filename.XPR
    • XPNCH=filename.XPH
    • XGET=filename.XGT
    • XPUT=filename.XPT
  • All of the above files are optional and will be opened on first access and closed at end of execution or end of file.  All files are ASCII with automatic conversion from or to EBCDIC.  ASCII file records have trailing spaces removed and end with carriage return x'0d' and line feed x'0a'.  On input fields are padded with EBCDIC spaces x'40'.  Non ASCII output bytes are converted to periods.
    • If a file operation is successful the condition code is set to 0 for XREAD, XGET, and XPUT. 
    • XPRNT and XPNCH do not set condition code.
    • At end of file for XREAD or XGET, the condition code 1 is set.
    • If a file error occurs on XREAD, XPRNT, XPNCH, the program aborts with abend code S013.
    • If a file open error occurs, program terminates with S013 abend with error message showing the file specification which failed.
    • If any other error occurs on XGET or XPUT such as missing length, condition code 2 is set.
  • Starting with z390 v1.4.01a the following additional changes have been made for ASSIST use:
    • The ASSIST option changes new option LOADHIGH to NOLOADHIGH which then casues programs to start loading at X'10000' instead of high end of memory.
    • Registers are initialized to X'F4', memory above the PSA is initialized to X'F5', and uninialized areas of 390 load modules are initialized to X'F6' (new in z390 PTF v1403d).  Use NOINIT override to revert to setting all these areas to X'00'.
    • A trace table is used to display the last 10 instructions prior to abnormal termination of a program when the TRACE option is off.
    • The PSW displayed at abnormal termination includes ILC, CC, MASK, and AMODE.
  • Example commands:
    • ASSIST assist\DEMOAST1 - assemble, link, and execute new ASSIST demo program which uses the ASSIST XDECO and XPRNT instructions to print prime numbers to 100.  See the follwoing files:
      • assist\DEMOAST1.MLC - source program
      • assist\DEMOAST1.PRN - generated assembly listing
      • assist\DEMOAST1.LOG - generated output log including all XPRNT output
      • assist\DEMOAST1.XPR - generated output file with all XPRNT lines.
    • ASSIST assist\TESTAST1 - assemble, link, and execute new ASSIST regression test named TESTAST1.MLC in the assist sub-directory.  After the command completes, the following files are available for viewing:
      • assist\TESTAST1.MLC - source assembler program with ASSIST instructions
      • assist\TESTAST1.ERR - error log with start/stop messages plus any error messages
      • assist\TESTAST1.PRN - assembly listing
      • assist\TESTAST1.LST - linker listing
      • assist\TESTAST1.LOG - execution log with XPRNT and XDUMP output
      • assist\TESTAST1.XRD - XREAD test input file
      • assist\TESTAST1.XPR - XPRNT output file
      • assist\TESTAST1.XPH - XPNCH output file
      • assist\TESTAST1.XGT - XGET test input file
      • assist\TEST\AST1.XPT - XPUT output file
    • ASSIST assist\TESTAST1 TRACE - add the TRACE option to generate TESTAST1.TRE output file with XPRNT, XDUMP, plus instruction trace for use in debugging.
    • ASSIST assist\TESTAST1 TEST - add the TEST option to start interactive test execution of the program with prompts for test commands which support tracing one or more instructions, dumping and/or changing registers and memory, etc.  Type H for help list of test commands.
  • Installation of z390 with ASSIST:
    • Uninstall any versions of z390 prior to v1.4.01 and delete the install directory z390.
    • Uninstall any versions of J2SE prior to 1.6.0
    • Download and install latest update for J2SE 1.6
    • Download and install z390 v1.4.01 for Windows or Linux
    • Download and install z390 cumulative PTF fixes v1.4.01
    • Double click z390 desktop icon to start GUI interface
    • Enter command ASSIST assist\TESTAST1 to run the ASSIST regression test
    • Enter edit assist\TESTAST1.LOG to view output log.
    • Enter command ASSIST assist\DEMOAST1 to run the ASSIST demo to print primes to 100.