tirsdag den 29. oktober 2019

Vector instructions (3)

This will be the last article regarding vectors.
This article deals with string (text) search which is finding the first occurrence of an element. An element can be a byte, halfword, or fullword. The string to search is in the second operand Vector Register and the element(s) to search for is(are) in the third Vector Register. The result is an offset to the element in the searched Vector Register (second operand). If you search for multiple elements the result is the first occurrence of any of the searched elements. My example will show it. 
In my example I will use byte search which you will most likely use. 
The instruction VFAEB will search for the first occurrence of either “D” or “C” in the text string “ABCDEFGHIJKLMNOP”.
Because “C” comes before “D” in the text string the result will be 2, - the offset to “C” in the text string.
        VL 1,V1_FLD,DOUBLEWORD_ALIGNED         
         VL    2,V2_FLD,DOUBLEWORD_ALIGNED         
         VFAEB 3,1,2,1                             
         VST   3,VECTOR_RESULT,DOUBLEWORD_ALIGNED  
         B     RETURN                              
VECTOR   DS 0D                                  
V1_FLD   DC CL16'ABCDEFGHIJKLMNOP'              
V2_FLD   DC CL2'DC' 
         DC    XL14'00'

The vectors will contain the results shown below.
VECTOR REGISTER VALUES                          
VR0...... 00000000  00000000 00000000 00000000
VR1...... C1C2C3C4  C5C6C7C8 C9D1D2D3 D4D5D6D7
VR2...... C4C30000  00000000 00000000 00000000
VR3...... 00000000  00000002 00000000 00000000

mandag den 21. oktober 2019

Vector instructions (2)

The Vector Instructions are also supporting Packed Decimal. However, not as true Vector but rather just Packed Decimal calculations in registers.
The traditional decimal instructions operate in storage areas as opposed to registers.
Packed Decimal Vector Instructions have been added to allow the quicker calculation in registers. 
You are supposed to load a packed decimal value into the Vector Register,
do your calculation(s) and then store it in storage again.
The decimal instructions calculate on the entire register.
The instructions below are an example of loading two registers with values,
then add them together, and store the result back into storage
DOUBLEWORD_ALIGNED EQU 3
WORD     EQU 2          
I4       EQU B'00011111'
M3       EQU B'0001'     

VECTOR_RESULT DS 2D

         VLEF  1,V1_FLD,3
        VLEF 2,V2_FLD,3
        VAP 3,1,2,I4,M3
        VST 3,VECTOR_RESULT,DOUBLEWORD_ALIGNED

VECTOR   DS 0D    
V1_FLD   DC PL4'1'
V2_FLD   DC PL4'2'
The VLEF (Vector Load Element Fullword) loads a fullword value from Vn_FLD into a Vector Register. The last operand tells which fullword in the register should be updated. In this case it the fourth and last fullword. The index is zero based, i.e. zero is the first and leftmost fullword and so on.
There are other Vector Load Element instructions. They are meant for other element sizes:

  • VLEB – Byte
  • VLEH – Halfword
  • VLEF – Fullword
  • VLEG – Doubleword

The VAP (Vector Add Packed decimal) adds the two Vector Registers together. I4 specifies the number of digits are allowed in the result. In this case I just said 32 which is the entire register. M3 sets the last bit to indicate that I want the condition code set according to the result.
The result of the program is:
VECTOR REGISTER VALUES
VR0...... 00000000 00000000 00000000 00000000
VR1...... 00000000 00000000 00000000 0000001C
VR2...... 00000000 00000000 00000000 0000002C
VR3...... 00000000 00000000 00000000 0000003C

torsdag den 17. oktober 2019

Vector instructions (1)

The new System z’s have included new instructions regarding vectors. Vectors are just fields with the same definition, - like integers etc. – located in a row in a general vector register. There are special registers for vectors that contains 16 bytes. Such a vector register can contain 8 halfwords, 4 fullwords, or 2 doublewords. A Vector instruction will do the same work on all fields in the Vector Register in parallel. For example, a Vector Add (VA) will add two Vector Registers together and save the result in a third Vector register.
VA    3,1,2,WORD
Add Vector Register 1 and Vector Register 2 and save the result in Vector Register 3. The values are contained in 4 fullwords.
VECTOR REGISTER VALUES
VR0......00000000 00000000 00000000 00000000  VR1......00000001 00000002 00000003 00000004
VR2......00000005 00000006 00000007 00000008  VR3......00000006 00000008 0000000A 0000000C


The machine instructions are somewhat different from instructions that we are used to. 
              00002 19 WORD     EQU 2
E731 2000 20F3                94 VA 3,1,2,WORD
The first byte is always X’E7’ for Vector Instructions. The last byte in the instruction will indicate the actual Vector Instruction. In this case X’F3’ tells that it is an add instruction. The assembler instruction VA is ended with a number, here 2, that tells the instruction that the vector register storage is divided in words, 4 bytes.
The following two instructions (VL) load contents into Vector Registers 1 and 2. The VA adds them together. The last (VST) stores Vector Register 3 into storage called “VECTOR_RESULT”
                      00003 18 DOUBLEWORD_ALIGNED EQU 3

000028                               24 VECTOR_RESULT DS 2D

000094 E710 B08E 3006       000B0 92 VL 1,V1_FLD,DOUBLEWORD_ALIGNED
00009A E720 B09E 3006       000C0 93 VL 2,V2_FLD,DOUBLEWORD_ALIGNED 
0000A0 E731 2000 20F3                94 VA 3,1,2,WORD              
0000A6 E730 C028 300E       00028 95 VST 3,VECTOR_RESULT,DOUBLEWORD_ALIGNED


It will be best practice to define the alignment of storage fields when you access real storage. That will speed up execution of the instructions.
The result of the VST instruction is
E5C5C3E3 D6D940D9 C5E2E4D3 E3404040 00000006 00000008 0000000A 0000000C   *VECTOR RESULT...*
The full program looks like this:
        PROGRAM EQU                             
DOUBLEWORD_ALIGNED EQU 3                         
WORD     EQU 2                                 
         PROGRAM STORAGE                         
         DS      CL24                            
EYECATCHER DS    CL16                            
VECTOR_RESULT DS 2D                              
         PROGRAM STORAGE                         
PGMVEC   PROGRAM START                           
         MVC   EYECATCHER,=CL16'VECTOR RESULT'   
         VL    1,V1_FLD,DOUBLEWORD_ALIGNED       
         VL    2,V2_FLD,DOUBLEWORD_ALIGNED       
         VA    3,1,2,WORD                        
         VST   3,VECTOR_RESULT,DOUBLEWORD_ALIGNED
         B   RETURN
VECTOR   DS 0D                                
V1_FLD   DS 0D                                
         DC    A(1)                              
         DC    A(2) 
         DC    A(3) 
         DC    A(4) 
V2_FLD   DS 0D   
         DC    A(5) 
         DC    A(6) 
         DC    A(7) 
         DC    A(8) 
         PROGRAM END
         END        
PGMVEC   BINDER     
         END        

søndag den 3. januar 2016

Unix from assembler (2) - Read a Unix File

Read a Unix File

Files on Unix and z/OS-datasets have complete different design paradigms. Nearly all files on z/OS have records. You read and write records. However, on Unix, you read and write bytes and/or a stream of bytes. When you wish to read, you say to the system how many bytes you want and you will get them until there are no more bytes in the file. Unix has a kind of records though, but they are merely bytes separated by Newline (NL - X’15’).

Unix files on z/OS

When you browse a file on zFS it looks exactly as records on a dataset with the exception that they have variable length. That is because each “record” is suffixed by X’15’ (New Line) and ISPF Browse shows it as a record. The NL is not displayed
********************************* Top of Data ***
------------------------------------------------
        MACRO                                   
444444444DCCDD                                   
00000000041396                                   
------------------------------------------------
&LABEL   USSSERV &SERVICE,&PARMS                 
5DCCCD444EEEECDE45ECDECCC65DCDDE                 
0312530004222595002595935B071942                 
------------------------------------------------
        GBLC  &PARM_LABEL                       
444444444CCDC445DCDD6DCCCD                       
00000000072330007194D31253                       
------------------------------------------------
        AIF   ('&SERVICE' EQ 'PARM').PARM       
444444444CCC444475ECDECCC74CD47DCDD754DCDD       
000000000196000DD02595935D0580D7194DDB7194       
Display of Unix file on zFS. (ISPF Browse)

If you enter the same file in edit mode, you see all lines padded with spaces but that is just for you to be able to type in characters after the last character. When you save the file an NL will be placed right after the last character and the spaces after NL will be removed.
****** ***************************** Top of Data *******
000001          MACRO                                   
      444444444DCCDD44444444444444444444444444444444444
      0000000004139600000000000000000000000000000000000
--------------------------------------------------------
000002 &LABEL   USSSERV &SERVICE,&PARMS                 
      5DCCCD444EEEECDE45ECDECCC65DCDDE44444444444444444
      0312530004222595002595935B07194200000000000000000
--------------------------------------------------------
Same file in edit mode

Assembler program to read a Unix file.

I have made a program that reads a file and write the “records” to operator (WTO). Let’s go through the sections in
the program. I use my macro USSSERV to do the more tedious work of calling the USS services. You can find it in the previous article

General storage fields and instructions

PARM     USSSERV PARM,10  
RETVAL   DS   F
RETCODE  DS   F
RSNCODE  DS   F
Definition of storage for all calls.

PARM as parameter list with 10 fullwords followed by three fullwords to return values from the callable service.

You must check for any error after each call.
        ICM   R15,B'1111',RETVAL  Test RETVAL
        BL    ERROR               Branch if negative
* (-1 = failure)

OPEN - BPX1OPN

First of all you must open the file you wish to read. The open will establish a connection between your program and the file. This specific connection is “pointed” to by the result of the open in the fullword FILEDESC which must be used in each of the following commands to the file, - here READ and CLOSE.
FILEDESC DS   F    Result field that contains a “pointer” to the file.
BUFLENA  DS   F    Length of Path and name of file
BUFFERA  DS   CL13 Path and name of file
FLAGS    DS   F    Open option. Read only (O_RDONLY)      
MODE     DS   F    Is here zero
Storage fields used by Open

Open the file for input (read) and save the file descriptor
        MVC   BUFFERA(14),=CL14'/u/jee/ussserv'
        MVC   BUFLENA,=F'14'
        XC    S_MODE,S_MODE
        XC    O_FLAGS(OPNF_LENGTH),O_FLAGS
        MVI   O_FLAGS4,O_RDONLY          Read only

        USSSERV OPEN,(BUFLENA,BUFFERA,FLAGS,MODE,
              RETVAL,
              RETCODE,
              RSNCODE)

        ICM   R15,B'1111',RETVAL  Test RETVAL
        BL    ERROR               Branch if negative
* (-1 = failure)
        ST    R15,FILEDESC        Store the file descriptor
Call open for read of “/u/jee/ussserv”. The result (File descriptor) is in register 15.

Remember, that path and file names are case sensitive.

READ - BPX1RED

You can now issue READ as many times you like until End-Of-File. The READ-command takes some fields.
READ_COUNT     DS F      Saves the result from R15 of bytes read
BUFFER         DS CL40   The area with the read bytes
BUFFER_ADR     DS F      The address of the area above
BUFFER_LENGTH  DS F      The length of the buffer area
B_ALET         DS F      Not used. Must be zero
READ fields

Before we call the READ service we must initiate some of the fields. The buffer (BUFFER) must be filled with binary zeroes in case we do not get all the bytes into the buffer. This will typically be at the end of the file.

Please note, that we supply the ADDRESS of the buffer rather than the buffer itself. It might be because we could issue another read right after adding the number of bytes read to the buffer address.  That would be convenient if the buffer is greater than the number we supply in the BUFFER_LENGTH. We do not do it here!
        LA    R4,WTOTEXT
LOOP_READ DS   0H
        MVC   BUFFER_LENGTH,=A(L'BUFFER)
        XC    B_ALET,B_ALET
        XC    BUFFER,BUFFER
        LA    1,BUFFER
        ST    1,BUFFER_ADR
                                                                   
        USSSERV READ,(FILEDESC,
              BUFFER_ADR,
              B_ALET,
              BUFFER_LENGTH,
              RETVAL,
              RETCODE,
              RSNCODE)
                                                                   
        ICM   R15,B'1111',RETVAL  Test RETVAL
        BM    ERROR               Branch if negative
* (-1 = failure)
        BZ    CLOSE               End-Of-File
        ST    R15,READ_COUNT      Store the number of bytes read
READ code

We check for any errors after the read and saves the number of bytes read in READ_COUNT.

Splitting a buffer into records

We must have a routine to convert the stream input to the record output.

WTO      DS    0F  
WTOLGD   DS    H   
WTOTEXT  DS    CL80
WTO fields

This routine takes the buffer and separates it into records that can be written to operator (WTO). One buffer can contain several records and a record can be split into two buffers. The routine checks for NL (X’15’) and when it is found it writes the record. However, when the routine comes to the end of the buffer without encountering an NL it goes to read a new buffer full of bytes.
        L     R6,READ_COUNT       
        LA    R2,BUFFER           
NEXT_BYTE DS   0H                  
        CLI   0(R2),X'15'         
        BE    WRITE_BYTES         
        MVC   0(1,R4),0(R2)       
        LA    R2,1(,R2)           
        LA    R4,1(,R4)           
        BCT   R6,NEXT_BYTE        
        B     LOOP_READ           
                                  
WRITE_BYTES DS 0H                  
        LA    R2,1(,R2)           
        MVC   WTOLGD,=Y(L'WTOTEXT)
        WTO   TEXT=WTO,ROUTCDE=11
        MVI   WTOTEXT,C' '        
        MVC   WTOTEXT+1(l'WTOTEXT-1),WTOTEXT  
        LA    R4,WTOTEXT                      
        BCT   R6,NEXT_BYTE                    
        B     LOOP_READ                       

Use of general registers:
R2 Points to the byte in the input buffer
R4 Points to the byte in the output buffer (WTOTEXT)
R6 Counts down the number of bytes left in the input buffer.

The number of bytes in the input buffer is limited to the input buffer length set on the READ command (BUFFER_LENGTH)


Close BPX1CLO

Nothing special with the CLOSE. It takes the FILEDESC and disconnects the program from the file.

CLOSE    DS    0h

        USSSERV CLOSE,(FILEDESC,
              RETVAL,
              RETCODE,
              RSNCODE)
                                                                   
        ICM   R15,B'1111',RETVAL  Test RETVAL
        BM    ERROR       Branch if negative (-1 = failure)
        BZ    RETURN


Manuals

UNIX System Services Programming: Assembler Callable Services Reference (SA22-7803-14)
EBCDIC Code Page: https://en.wikipedia.org/wiki/EBCDIC_037