12 Vortex Coding Tips

Over time we've found some tips that make Vortex scripts easier to write and maintain:

  • Indent blocks

    Indent code of equal block depth equal amounts:

    
      <A NAME=func PUBLIC>
        Start
        <IF $x eq 1>
          <IF $y eq 2>
            x is 1 and y is 2
          <ELSE>
            something else is true
          </IF>
        </IF>
      </A>
    

    This makes code more readable, and since Vortex strips leading spaces from the output, there's no wasted network bandwidth. (Some HTML generators are copious space wasters.)

  • Declare function scope

    Always declare a function's scope in any significant application. Because of back-compatibility rules, Vortex may change the implicit scope of a function from what you expect.

  • Declare lowest needed scope

    Don't make a function PUBLIC unless it has to be. You don't want accidental or intentional running of sensitive functions.

  • Use header/footer functions

    Every page in an app usually has common HTML for the top and bottom, so why not put that in a separate pair of functions? We usually call them look and /look for symmetry:

    
      <A NAME=look PRIVATE>
        <BODY BGCOLOR=white>
      </A>
    
      <A NAME=/look PRIVATE>
        </BODY>
      </A>
    
      <A NAME=main PUBLIC>
        <look>
        This is main.
        </look>
      </A>
    

    This way, a function can concentrate on its page's unique HTML without clutter. It also makes it easy to change the overall look and feel of the app.

    Our examples in this tutorial sometimes omit these functions, but only for brevity.

  • Use macro functions

    It's often useful to write "macro" functions in Vortex, to encapsulate commonly used HTML sequences. For example:

    
        <A NAME=fn>
          <SPAN STYLE="color: #BOBOBO; font-family: Courier">
        </A>
    
        <A NAME=/fn>
          </SPAN>
        </A>
    
        <A NAME=main>
          We have <fn>many</fn> different <fn>font</fn> changes
          in <fn>this</fn> example.
        </A>
    

    This not only cleans up the code and saves time, it makes it trivial to change the font look/feel later - only one function to change.

  • <sum> and <substr> to make a CSV list

    The <sum> function can be used to concatenate a list into a comma-separated-value string:

    
        <$x = "A" "list" "of" "words">
        <sum ",%s" "" $x>
        <substr $ret 2 -1>
    

    We use <substr> afterwards to strip off the leading two commas: one for our empty string (forces string cat), and one from the first "real" value of $x .

  • Append all values, then sum at end

    It's more efficient to append multiple values in a list, and sum the values all at once, than to sum multiple times:

    
        <A NAME=func>
          <$x = >
          ...
          <$x = $x $One>
          ...
          <$x = $x $Two>
          ...
          <$x = $x $Three>
          <sum "%s" "" $x>
          <$x = $ret>
        </A>
    

    instead of:

    
        <A NAME=func>
          <$x = >
          ...
          <sum "%s" "" $x $One>
          <$x = $ret>
          ...
          <sum "%s" "" $x $Two>
          <$x = $ret>
          ...
          <sum "%s" "" $x $Three>
          <$x = $ret>
        </A>
    

  • Use <sum> instead of SQL math

    <sum> is faster than a math statement, and does not require a Texis database handle:

    
        <sum "%s" "" $x $y>
        is faster than:
        <$ret = ('' + $x + $y)>
    

  • Printing a full binary value

    Not all functions in Vortex can accept full binary (varbyte) data; many stop at nul (a 0 byte). <fmt> is binary compatible; use it to print a varbyte field as-is in its entirety, no escapement and no truncation.

  • Check the <SQLCACHE> setting

    If you're doing a lot of the same <SQL> s, or a lot of Texis math statements (with parens), repeatedly in a loop, up the <SQLCACHE> value at the top of the script. This can make SQL run faster as more handles are used to cache statements.

  • UPDATE, INSERT and DELETE return rows

    Not only SELECT statements, but UPDATE and DELETE return rows in <SQL> . This can save a table read in some cases. For example, if we have a password table with user name, password, last login time, and permissions, we can verify the user name and password, update the last-login, and get the user's permissions, all in one statement:

    
      <SQL MAX=1 "update passwd set LastLogin = 'now'
                  where User = $user and Pass = $pass">
      </SQL>
    

    Even though we didn't select anything, and only updated one column, we will get back the entire updated row. This saves us having to select it right after.

  • Use NOVARS, MAX=1 for most non-selects

    The flip side of the above example is that we might unintentionally set Vortex variables as the result of a DELETE or UPDATE . Unless you really want the returned data (as we did above), use NOVARS to make sure no vars are disturbed:

    
      <SQL MAX=1 NOVARS "delete from tbl where id = $id"></SQL>
    

    Without the NOVARS , all the columns from our delete would set variables in Vortex as if it were a select.

    Also, we used MAX=1 to ensure only one row was deleted, when we only want one row deleted. If $null was set and $id was empty, then without the MAX=1 , the entire table would be deleted! (The where clause went away due to $null .) MAX=1 is a "safety" here: at worst only 1 wrong row is deleted if $id is unset.

  • Check the log and HTML source for errors

    If your script suddenly does nothing, or the unexpected, look at the HTML source of the output in your browser, and check /usr/local/morph3/texis/vortex.log (or c:\morph3\texis\vortex.log under Windows) for errors. They can provide the exact location and details of what went wrong.

  • Scan the manual for useful functions

    Vortex was designed for web sites; chances are it's got a feature that'll help you. Scan the manual and look at what those other functions do; maybe they'll come in handy. If you don't see a way to do something, ask tech support.

  • Use <CAPTURE> to copy output

    The <CAPTURE> function is like file redirection: it captures the output of a given block of Vortex code. This is useful for complex string construction: just print the values out in a <CAPTURE> block, instead of a long <strfmt> or concatenation statement.

  • Tie in other programs with <EXEC>

    The <EXEC> statement runs an arbitrary program. It's a quick and easy way to obtain data from another process into Vortex.

  • Cookies with <header>

    The <header> function can produce arbitrary headers for your script, such as redirects and cookies.

  • Flush output before SQL

    <SQL> statements sometimes take a while. Make sure that your users at least see the output you've produced up to that point while they wait, by calling <flush> just before any code that might take a while.

    Back: Other Module Options Next: Common Vortex Mistakes
  • Copyright © 2024 Thunderstone Software LLC. All rights reserved.