Zbex special variables and labels

Previous chapter Handling directories

Zbex Manual

Next Chapter Instructions for debugging

Some of the material covered in this section has also been presented in other sections. This is because all special variables and special labels are related to some aspect of the operation of Zbex.

There are six special variables: err, rem, mpt, sub, sze, and trp. These variables are integer type and are automatically included in your program (with declaration).

err

This variable takes on meaning only when bit 12 of the zoperation flag is set. (see Section 18.3 on how to do this using the setflag instruction).

Under default operation (bit 12 of zoperation flag is clear = 0), when a Zbex open instruction fails for any reason, Zbex sends a prompt to the user asking for a new (different) file name. The program is suspended until this supplied. Sometimes, however, the user does not welcome this interruption; if the file or directory can't be opened, the user wants the program to ignor the open request and move on. This will happen if bit 12 of the zoperation flag is set = 1..

In this case, how does the user's program know that open has failed, and why? Answer, Zbex sets the special variable err to one of the following values:

                0  =  open was successful 
                1  =  cannot expand to full file name 
                2  =  file already open somewhere else 
                3  =  cannot open the file at all 
                4  =  not a file or a directory 
                5  =  unable to read directory 
                6  =  read access on file is denied 
                7  =  cannot open file for writing 
                3  =  cannot open the file at all 
                8  =  writing allowed only on regular files 
                9  =  read/write access on file is denied 
                10 =  write access on file is denied 
                11 =  cannot create new file 

Program control moves on to the next Zbex instruction, which almost certainly would be to test the value of err.

rem

This variable is assigned a value every time an integer divide is performed. If more than one integer divide is performed in a statement, the value of rem will be set by last integer divide to be performed by the statement. The sign of rem is always the sign of the dividend. Example:

              Program 
        --------------------- 
        int q 
     
        q = 13 / 9 
        putc for 13 / 9,   quotient = ~q     rem = ~rem 
        q = -13 / 9 
        putc for -13 / 9,  quotient = ~q     rem = ~rem 
        q = 13 / -9 
        putc for 13 / -9,  quotient = ~q     rem = ~rem 
        q = -13 / -9 
        putc for -13 / -9, quotient = ~q     rem = ~rem 
        run 

                     Execution 
        ------------------------------------- 
        ** S=11, P=98, L=237, M=410 ** 
        for 13 / 9,   quotient = 1     rem = 4 
        for -13 / 9,  quotient = -1    rem = -4 
        for 13 / -9,  quotient = -1    rem = 4 
        for -13 / -9, quotient = 1     rem = -4 
        Ready for program 

mpt

This variable is affected by two types of statements.

1. If the "con" operator in a relation is successful, mpt is assigned the number which is the position in the left hand string where the "con" operate found a match.
2. When the txt function appears with only two of its three required variables, mpt is assumed to be the third variable. If the txt function is successful in parsing a sub-string from the source string, mpt will be set to the subscript of the parsing byte (see section on functions).

Example:

              Program 
        --------------------- 
        str a.10,b.10 
     
        putc Testing mpt with con 
        putc -------------------- 
        a = "Elmer Fudd" 
        if a{3..5} con "er" 
          putc "er" occurs at position ~mpt  in "~a{3..5} " 
        end 
        putc 
        putc Testing mpt in txt 
        putc ------------------ 
        mpt = 1 
        putc mpt = ~mpt 
        b = txt(a,[32]) 
        putc First word = ~b 
        putc mpt = ~mpt 
        run 

                     Execution 
        ------------------------------------- 
        ** S=11, P=66, L=255, M=418 ** 
        Testing mpt with con 
        -------------------- 
        "er" occurs at position 2 in "mer" 
     
        Testing mpt in txt 
        ------------------ 
        mpt = 1 
        First word = Elmer 
        mpt = 6 
        Ready for program 

sub

This variable is affected by two types of statements.

1. If the "con" operator in a relation is successful, sub is assigned the subscript in the left hand (string) variable where the "con" operate found a match. match.
2. The int(str) and flt(str) functions assign to sub the subscript of the first byte which is not part of the integer format (or real number format). Examnple:

              Program 
        --------------------- 
        str a.20 
        int i 
        real x 
     
        putc Testing sub with con 
        putc -------------------- 
        a = "Elmer Fudd" 
        if a{3..5} con "er" 
          putc "er" occurs at subscript ~sub  in "~a " 
        end 
        putc 
        putc Testing sub with int(str) and flt(str) 
        putc -------------------------------------- 
        putc a = "  234.890;  " 
        a = "  234.890;  " 
        sub = 1 
        putc sub = ~sub 
        i = int(a)
        putc Integer value = ~i 
        putc sub = ~sub 
        putc 
        sub = 1 
        putc sub = ~sub 
        x = flt(a)
        putc Real value = ~x 
        putc sub = ~sub 
        run 

                     Execution 
        ------------------------------------- 
        ** S=26, P=152, L=255, M=416 ** 
        Testing sub with con 
        -------------------- 
        "er" occurs at subscript 4 in "Elmer Fudd" 
   
        Testing sub with int(str) and flt(str) 
        -------------------------------------- 
        a = "  234.890;  " 
        sub = 1 
        Integer value = 234 
        sub = 6 
    
        sub = 1 
        Real value = 234.89 
        sub = 10 
        Ready for program 

sze

This variable is assigned a value when you open a file for type 5 access (random read/write). The value is the number of bytes in the file being opened. You will need this number in order to avoid reading beyond the end of the file.

trp

This variable is assigned a value when a return statement with a literal integer is encountered. The value is the value of the integer.

Special labels

There are eleven special labels; trap, brk, and eof1 to eof9. The trap and brk labels should be used only in the main part of your program, i.e., not in procedures.

trap

The trap label, if used, marks the location in the main program where control is transferred when an abnormal return is encountered in a procedure. An abnormal return from a procedure clears the entire procedure return stack and assigns a value to the special integer variable trp.

brk

The brk label, if used, marks the location in the main program where control is transferred when the break key is pressed. If the break procedure is present, this will override the transfer to brk. If neither the brk lable nor the break procedure is present, pressing the break key will terminate the program. Examples:

(1) with brk only.

               Program 
         --------------------- 
               loop 
               repeat 
         brk: 
               putc Break pressed 
               run 

                      Execution 
         ------------------------------------- 
         ** S=5, P=11, L=231, M=410 ** 
         Break pressed 
         Ready for program 

(2) with brk and the break procedure

               Program 
         --------------------- 
               loop 
               repeat 
         brk: 
               putc Break pressed 
               stop 
    
               procedure break 
                 putc Break pressed, what now?  
                 getc 
               return 
               run 

                      Execution 
         ------------------------------------- 
         ** S=10, P=23, L=231, M=410 ** 
         Break pressed, what now?  
                                      (blank line entered) 
         Break pressed, what now?  
         !!  
         Ready for program 

eof1

The eof1 label, if used, may appear anywhere in a program, including inside a procedure. The eof1 location is the entry point for program control following an attempt to getf a record sequencially beyond the last record in a file opened with a tag of [1]. The special labels, eof2 to eof9 work in a similar fashion.

<hline noshade>

Clearly, some caution must be exercised in the use of the special labels. Since these labels may be placed inside loops with counters, it is possible to jump into such a loop without having set up the counter variable or its limits. This could lead to unpredictable run time results. More seriously, the eof labels can be placed in procedures which may not be properly called at run time. The following program will bomb the the interpreter, because the return from the procedure "death" cannot be properly executed.

               Program 
         --------------------- 
             open [1,1] "<an existing file>" 
             loop 
               getf [1] 
             repeat 
             putc Congratulations!  You've done the impossible.  
             stop 
         * 
             procedure death 
         eof1: 
             return

Previous chapter Handling directories

Zbex Manual

Next Chapter Instructions for debugging