home *** CD-ROM | disk | FTP | other *** search
/ ftp.robelle3000.ai 2014 / 2014.06.ftp.robelle3000.ai.tar / ftp.robelle3000.ai / changes / supr4p7ux.txt < prev    next >
Text File  |  2005-07-18  |  68KB  |  1,854 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                             SUPRTOOL Version 4.8.01
  7.  
  8.  
  9.                           Database Handyman for HP-UX
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                  Change Notice
  17.                            Installation Instructions
  18.                           Addendum to 4.6 User Manual
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                             Suprtool         4.8.01
  26.                             Suprlink         4.8.01
  27.                             STExport         4.8.01
  28.                             Dbedit           4.8.01
  29.                             Suprtool2        4.8.01
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                          Robelle Solutions Technology
  41.                           Suite 372, 7360 137 Street
  42.                            Surrey, BC Canada V3W 1A3
  43.  
  44.  
  45.  
  46.                              Phone:  604.501.2001
  47.                               Fax:  604.501.2003
  48.  
  49.                          E-mail:  support@robelle.com
  50.                              Web:  www.robelle.com
  51.  
  52.                                   April 2004
  53.           Program  and  Manual  Copyright  Robelle Solutions Technology Inc.
  54.           1981-2004
  55.  
  56.  
  57.           Permission is granted  to  reprint  this  document  (but  not  for
  58.           profit), provided that copyright notice is given.
  59.  
  60.  
  61.  
  62.  
  63.           QEDIT  and SUPRTOOL are trademarks of Robelle Solutions Technology
  64.           Inc.  Other product and company names mentioned herein may be  the
  65.           trademarks of their respective owners.
  66.  
  67.  
  68.  
  69.    Introducing Suprtool/UX Version 4.8.01
  70.  
  71.  
  72.                *  Highlights
  73.                *  Known Problems
  74.                *  Compatibility
  75.                *  CPU Serial Number (uname)
  76.                *  Documentation
  77.  
  78.           Use  Suprtool/UX  to  read,  select,  and  sort  data from Oracle,
  79.           Eloquence  and  Allbase  databases  and  from  data   files   with
  80.           fixed-length  records.   Suprtool/UX  is designed to be similar to
  81.           Suprtool  for  MPE  while  providing  necessary  HP-UX   features.
  82.           Suprlink/UX  provides high-speed data-file linking based on a sort
  83.           key.  Use STExport to convert fields in  a  self-describing  input
  84.           file  into  an  output  file  that  can be imported into different
  85.           applications.
  86.  
  87.  
  88.    Highlights in Version 4.8.02
  89.  
  90.  
  91.           *   The information about the data loaded in a Table would be lost
  92.              if  the tabl being referenced was the second held table and the
  93.              previous task involved a chai command.
  94.  
  95.           *  The Get command would not get correct end of file signal if the
  96.              dataset was empty and being accessed with Set FastRead On.
  97.  
  98.  
  99.    Highlights in Version 4.8.01
  100.  
  101.  
  102.           *  The  Chain  command would not return the correct record if used
  103.              with Set FastRead On.
  104.  
  105.  
  106.    Highlights in Version 4.8
  107.  
  108.  
  109.           *  The Clean command in Suprtool would incorrectly  upshift  lower
  110.              case alpha characters.
  111.  
  112.           *  The  $edit  function  will  now  work  when nested within other
  113.              string functions
  114.  
  115.           *  The List command on HPUX now has the RECLEN parameter.
  116.  
  117.           *  Suprtool now has the command Set Oracle ZeroNull On |Off  which
  118.              optionally turns null values into zeros.
  119.  
  120.  
  121.    Highlights in Version 4.7.12
  122.  
  123.  
  124.           *  The $subtotal function has been re-written in order to use less
  125.              resources and fix some bugs.
  126.  
  127.           *  Suprtool now reads Eloquence databases up to five times faster.
  128.  
  129.           *  Eloquence  routines  are  now  dynamically  loaded,  using  the
  130.              libraries on your system.
  131.  
  132.           *  The $split command can now trim off leading and trailing  quote
  133.              characters in "PRN" files.
  134.  
  135.  
  136.    Highlights in Version 4.7.11
  137.  
  138.  
  139.           *  Suprtool now has a $findclean function to identify records with
  140.              specific characters in it.
  141.  
  142.           *  Dbedit for HP-UX now works on HP Eloquence databases.
  143.  
  144.           *  There is a new version of Suprtool that works with IMAXSoft.
  145.  
  146.           *  The List command now has new options for listing to a  file  on
  147.              HP-UX.
  148.  
  149.           *  The $subtotal function would not work if the previous task used
  150.              the Dup None Keys feature.
  151.  
  152.           *  The $total function would appear to total data incorrectly when
  153.              sorting on the field that was being totalled.
  154.  
  155.           *  Variables  that  resolved  to all spaces for the entire command
  156.              line would not work.
  157.  
  158.           *  The $subtotal function would  not  work  at  times  due  to  an
  159.              uninitialized variable.
  160.  
  161.  
  162.    Highlights in Version 4.7.10
  163.  
  164.  
  165.           *  Suprtool now has a $edit function for formatting data.
  166.  
  167.           *  Suprtool now allows up to 255 $split functions per task.
  168.  
  169.           *  Suprtool's  Open  command  can  now  connect to a remote Oracle
  170.              database.
  171.  
  172.           *  Numrecs 100% would come up with the wrong output file size when
  173.              reading very large files.
  174.  
  175.           *  The  new  $split  function  would  put random characters at the
  176.              point where the split would occur in some cases.
  177.  
  178.           *  The new $split function would incorrectly report an error in  a
  179.              second task multiple $split operations.
  180.  
  181.           *  The  new $number function did not handle numbers that consisted
  182.              of only a decimal place followed by any number of zeroes and  a
  183.              number, as in .01 thru .09
  184.  
  185.           *  Suprlink would abort if the Join file was empty.
  186.  
  187.           *  Suprlink  would  hold  the  Join  file  open after the task was
  188.              completed.
  189.  
  190.           *  Suprtool  would  total  incorrectly  when  using  a   $subtotal
  191.              function.
  192.  
  193.           *  The  form  command  would display the percentage full as a very
  194.              large strange number if the capacity and the entries were  both
  195.              zero for Eloquence databases.
  196.  
  197.           *  Update  ciupdate would not be effective for Eloquence databases
  198.              in the case where Ciupdate was allowed.
  199.  
  200.           *  We have worked around an Oracle patch issue which  stopped  the
  201.              Open command from being able to connect to an Oracle database.
  202.  
  203.  
  204.    Highlights in Version 4.7.02
  205.  
  206.  
  207.           *  Suprtool would report an incorrect error message when using the
  208.              $number function in some cases.
  209.  
  210.           *  A Dbupdate of a critical item or sort item would fail  in  some
  211.              cases due to a small bug in Eloquence.
  212.  
  213.  
  214.    Highlights in Version 4.7.01
  215.  
  216.  
  217.           *  The  Base  command  would  fail  in  some  cases with a Dblogon
  218.              message from Eloquence.
  219.  
  220.           *  A Dbupdate of a critical item or sort item would fail  in  some
  221.              cases.
  222.  
  223.  
  224.    Highlights in Version 4.7
  225.  
  226.  
  227.           *  Suprtool   would   report   an  incorrect  record  number  when
  228.              encountering an Illegal  ascii  digit,  if  the  Suprtool  task
  229.              involved the Duplicate command.
  230.  
  231.           *  Suprtool  now  has a $Number function which will allow Suprtool
  232.              to use a freeform ascii number with signs, decimal  places  and
  233.              currency symbol as a display field.
  234.  
  235.           *  STExport  would in some cases attempt to format data in XML and
  236.              HTML.
  237.  
  238.           *  The Clean command in STExport and Suprtool has improved  syntax
  239.              to define a range of characters to replace.
  240.  
  241.           *  Suprtool now has a $SubTotal function.
  242.  
  243.           *  Suprtool  can  now  split byte strings into multiple fields via
  244.              the $split function.
  245.  
  246.           *  Suprlink can now do many-to-many links via the Join command.
  247.  
  248.           *  Suprlink and STExport now report the number of  output  records
  249.              in a manner similar to Suprtool.
  250.  
  251.           *  The $counter function was not reset in between tasks.
  252.  
  253.           *  Extract  from a table would incorrectly report an error in some
  254.              cases.
  255.  
  256.           *  Suprtool  for   HP-UX   now   supports   environment   variable
  257.              substition.
  258.  
  259.           *  The Table command now supports filenames up to 80 characters.
  260.  
  261.           *  The  Table  command  truncated  filenames  at  the  limit of 36
  262.              characters.
  263.  
  264.           *  The number of defines allowed in Suprtool has been increased to
  265.              768.
  266.  
  267.           *  Suprtool   has  been  enhanced  to  support  HP  Eloquence  7.0
  268.              features.
  269.  
  270.           *  The Base and Put commands have  been  changed  to  support  new
  271.              syntax.
  272.  
  273.           *  Suprtool  now  supports  the  expanded  database  limits  in HP
  274.              Eloquence 7.0.
  275.  
  276.           *  Suprtool now support extract from a table and larger tables  on
  277.              HP-UX.
  278.  
  279.           *  Suprtool and STExport now support features to Clean your data.
  280.  
  281.           *  STExport  now  supports an Escape command which will escape out
  282.              certain characters.
  283.  
  284.           *  Suprtool now supports a $Counter function which will  increment
  285.              a field for every record selected.
  286.  
  287.           *  Suprtool  now  supports  a  $total  function which will total a
  288.              specified field.
  289.  
  290.           *  Suprtool would incorrectly coerce large negative numbers from a
  291.              Packed field to another Packed or Display field.
  292.  
  293.           *  Suprtool would fail with prefetch point failure if the file had
  294.              an uneven record size and an uneven blocking facter.
  295.  
  296.           *  STExport now properly converts the Roman 8  universal  monetary
  297.              symbol to the Euro-Symbol in the HTML and XML commands.
  298.  
  299.           *  The Item command would fail if a definition or Item command was
  300.              already  issued  for  a  field,  if  the  input  source  was  a
  301.              self-describing  file  and   and  extract range was used or all
  302.              items from a dataset were extracted.
  303.  
  304.           *  The XML command would fail to convert ">" to ">" and "<"  to
  305.              "<".
  306.  
  307.           *  The XML and HTML commands failed to convert "&" to "&".
  308.  
  309.           *  Suprtool  incorrectly  rounded  Real  and  Long  target data in
  310.              arithmetic expressions.
  311.  
  312.  
  313.  
  314.    Known Problems
  315.  
  316.           There are two known issues associated with the  Oracle  interface.
  317.           In  order  to  fix a problem introduced by a patch to Oracle 9, we
  318.           had to change to a new Oracle call interface call.  You can invoke
  319.           this new call in one of two methods:
  320.  
  321.             1) Set Oracle OpenFix On
  322.             2) Specify the Username and Password in the following manner
  323.                open oracle scott/tiger
  324.  
  325.           When using this type of syntax and the Open command is preceded by
  326.           a system command, such as echo, the Open command will fail with  a
  327.           core  dump.   The  work  around  is to not have the system command
  328.           before the open command.
  329.  
  330.           When connecting to a remote machine using the syntax:
  331.  
  332.             open oracle username/password@machine
  333.  
  334.           Suprtool uses the different method for connecting to  a  database,
  335.           which  for some reason fails on the second and fourth connections.
  336.           While we normally would not release software  with  this  kind  of
  337.           defect, we have done so for two reasons:
  338.  
  339.             1) We cannot find any reason in our code for the problem and the
  340.             failure appears to occur inside the Oracle call.
  341.             2) Some customers that need the functionality to connect to a
  342.             remote machine are willing to live with the problem.
  343.  
  344.           Suprtool 4.6 and Suprtool 4.7 by default would  forcefully  return
  345.           zeroes  for fields which were considered null.  It is important to
  346.           note that Suprtool would return zeroes for Null fields, it is just
  347.           Suprtool  4.6  and  4.7  forced  this  as  some  null fields for a
  348.           customer were corrupt.  We have made this optional with Set Oracle
  349.           NullZero with the default being off.
  350.  
  351.           Suprtool  by  default  no  longer  forces  zeroes for null numeric
  352.           fields as Suprtool incorrectly zeroes out a field  if  the  Select
  353.           statement contains the to_char function and has the field has null
  354.           values.
  355.  
  356.           This should be fixed in a future version of Suprtool.
  357.  
  358.           If you have any questions or concerns or feedback on these or  any
  359.           other issue, please feel free to e-mail me at: neil@robelle.com
  360.  
  361.  
  362.  
  363.    Compatibility
  364.  
  365.           Suprtool/UX  is  compatible  with HP-UX 9.0, all versions of HP-UX
  366.           10.x, all versions of  HP-UX  11.x,  as  well  as  Oracle  version
  367.           7.1.3.2.0.
  368.  
  369.           On  HP-UX  10.x,  Suprtool/UX  creates  all  of  its temporary and
  370.           scratch  files  in  /var/tmp,  unless  you  have  overridden   the
  371.           temporary directory with the TMPDIR environment variable.
  372.  
  373.           Suprtool  for  HP-UX  typically  comes  with  two  versions in two
  374.           different directories on your tape.  The version  of  Suprtool  in
  375.           /opt/robelle  is  compatible  with  HP-UX  10.20  and  later.  The
  376.           version of Suprtool in /usr/robelle is  compatible  with  versions
  377.           earlier than HP-UX 10.20.
  378.  
  379.           Previously   Suprtool  would  truncate  a  Table  filename  at  36
  380.           characters if the filename was  greater  than  36  characters  and
  381.           therefore  would  open a file if a file existed at the previous 36
  382.           character limit.  The Table filename  has  been  increased  to  80
  383.           characters.   If the Table filename exceeds 80 characters Suprtool
  384.           will print an error.
  385.  
  386.  
  387.  
  388.    CPU Serial Number (uname)
  389.  
  390.           This program runs only on CPUs  whose  serial  numbers  have  been
  391.           encoded (the "uname" on HP-UX).  If it fails to run and you get an
  392.           "invalid HPSUSAN" error message, call Robelle for assistance.
  393.  
  394.  
  395.    Documentation
  396.  
  397.           The user manuals for Suprtool and its components are all available
  398.           in  the several popular formats such as PDF and HTMLHelp.  You can
  399.           also order  hardcopy  manuals  from  our  printing  service.   All
  400.           downloads and information is available in our library at:
  401.  
  402.  
  403.              http://www.robelle.com/library/manuals/
  404.  
  405.           The  manuals  are  also included as help files within the Suprtool
  406.           program and can be accessed by typing the help command:
  407.  
  408.             >help
  409.  
  410.  
  411.    Installation of Suprtool for HP-UX
  412.  
  413.  
  414.           The new version overwrites an existing version of Suprtool on your
  415.           HP-UX  system.   Please  do not use these instructions if you have
  416.           downloaded our software from the Web.
  417.  
  418.           You can find the instructions for the  Web  download  installation
  419.           here:
  420.  
  421.           http://www.robelle.com/downloads/install-sxprod.html
  422.  
  423.           This  page  assumes  that you have already downloaded the tar file
  424.           from our web site.
  425.  
  426.           If you have received a tape from us you can find the  installation
  427.           instructions here:
  428.  
  429.           http://www.robelle.com/support/install/tape/sxprod.html
  430.  
  431.  
  432.  
  433.    Enhancements in Version 4.8
  434.  
  435.  
  436.           We  constantly  provide  Suprtool  users  with  new features.  The
  437.           following section describes the new enhancements to Suprtool since
  438.           for the last two years.
  439.  
  440.  
  441.    Set Oracle ZeroNull
  442.  
  443.           Suprtool  for  HP-UX  has  a  new  option to turn on changing null
  444.           fields to zeroes.  Set Oracle ZeroNull On will change  any  fields
  445.           that are "null" (in the SQL sense of the word), will become zeroes
  446.           for the appropriate number type.
  447.  
  448.           In order to turn this feature on for all accesses you can put  the
  449.           command:
  450.  
  451.             Set Oracle ZeroNull On
  452.  
  453.           into the file /opt/robelle/suprmgr.
  454.  
  455.           Previous  to  version  4.6  in  Suprtool used to return nulls, but
  456.           Suprtool 4.6 and  Suprtool  4.7  would  return  zeroes.   We  have
  457.           decided  to  make  this  optional  and  make the default to return
  458.           Nulls, due to problems when using  the  to_char  function  in  the
  459.           select  statement.   See  the  Compatibility  section  for  a more
  460.           detailed explanation.
  461.  
  462.  
  463.    Reclen on List command
  464.  
  465.           Suprtool for HP-UX can output data from  the  List  command  to  a
  466.           discfile.   Although the concept of record size is not the same on
  467.           HP-UX as it is on MPE it is still important in some  areas  within
  468.           Suprtool.
  469.  
  470.           In  this  case the RECLEN parm merely tells the List command where
  471.           to fold the lines.  The Reclen parm can be a value from 56 to  256
  472.           and defaults to 80 bytes.
  473.  
  474.             >List FILE myreport RECLEN 132
  475.  
  476.  
  477.  
  478.    Enhancements in 4.7.12
  479.  
  480.  
  481.    FastRead
  482.  
  483.           Suprtool  for HP-UX by default calls dbget to do serial reads, now
  484.           with Suprtool you can utilize faster reads with the  Set  FastRead
  485.           On  command.   This  command  invokes  more efficient large reads.
  486.           Testing has shown that the CPU time can be  improved  by  anywhere
  487.           from  two  to  five times and Wall time has improved anywhere from
  488.           two to six times faster.  In order to turn this feature on for all
  489.           accesses you can put the command:
  490.  
  491.             Set FastRead On
  492.  
  493.           into the file /opt/robelle/suprmgr.  This means that Suprtool will
  494.           use the faster reads for all runs of Suprtool.
  495.  
  496.  
  497.    Dynamic Load
  498.  
  499.           Suprtool for HP-UX attempts  to  dynamically  load  the  Eloquence
  500.           routines.   Suprtool  requires  two  Eloquence  libraries, namely:
  501.           libimage3k.sl and libeqdb.sl.  What Suprtool now does is look  for
  502.           these  libraries  in  two separate ways.  First Suprtool looks for
  503.           libeqdb.sl and libimage3k.sl in any of the  directories  named  in
  504.           the  SHLIB_PATH  variable.   For  example  to insure that Suprtool
  505.           resolves the library loads you can set the SHLIB_PATH system  wide
  506.           in your /etc/profile file in the following manner:
  507.  
  508.            # add SHLIB_PATH for Eloquence library search
  509.               export SHLIB_PATH=/opt/eloquence6/lib/pa11_32
  510.  
  511.           The  line proceeding the export command is a comment line and does
  512.           not need to be in the file, but is just a  reference  to  indicate
  513.           what it is used for.
  514.  
  515.           If  you  do  not have the SHLIB_PATH variable set to a value where
  516.           libeqdb.sl and libimage3k.sl can be found, Suprtool will then  try
  517.           to load libimage3k.sl in the directory /opt/eloquence6/lib/pa11_32
  518.           and libeqdb.sl from the same directory.  If  the  libraries  still
  519.           fail  to be loaded then Suprtool will print two warnings, however,
  520.           it will still continue to function,  just  any  of  the  Eloquence
  521.           features will fail when called:
  522.  
  523.             Warning: Could not load Eloquence image library
  524.             Warning: Could not load Eloquence scan library.
  525.  
  526.  
  527.  
  528.    Enhancements in 4.7.11
  529.  
  530.  
  531.  
  532.    Dbedit Module
  533.  
  534.           The  Dbedit  Module  has  been  enabled in Suprtool for HP-UX.  It
  535.           works with Eloquence databases and with Oracle databases with  the
  536.           IMAXSoft version of Suprtool.
  537.  
  538.           The  Dbedit  Manual will be in the Suprtool for HP-UX 4.8 release.
  539.           In the meantime you can use the MPE version of the manual.
  540.  
  541.  
  542.    $Findclean Function
  543.  
  544.           We recently added the $Clean function  to  primarily  clean  "bad"
  545.           characters  in  text  fields.   This  has  been  extremely popular
  546.           enhancement but many wanted to do investigative work  and  try  to
  547.           figure  out  what  records  had these bad characters, to hopefully
  548.           where the "bad" data was coming from.
  549.  
  550.           For  this  reason  we  have  created  the   $FindClean   function.
  551.           $FindClean  will return true if it finds a character defined using
  552.           the Clean command.
  553.  
  554.             >in cleansd
  555.             >clean "^9","^10"
  556.             >if $findclean(nonprint)
  557.             >list
  558.  
  559.           The above task will list the record if the field  nonprint  has  a
  560.           Tab (Decimal 9) or a Line Feed (Decimal 10) anywhere in the field.
  561.  
  562.           You can Find and clean the "bad" characters from a  field  at  the
  563.           same time:
  564.  
  565.             >in cleansd
  566.             >clean "^9","^10"
  567.             >if $findclean(nonprint)
  568.             >extract nonprint=$clean(nonprint)
  569.             >list
  570.  
  571.  
  572.  
  573.    List Command
  574.  
  575.           The  List  command  has been enhanced with a new File keyword that
  576.           allows output to be directed to a file.  The List command also has
  577.           a new option to Append to an existing file.
  578.  
  579.           The File option takes the next parameter as being the filename:
  580.  
  581.             >in test/file1sd
  582.             >list stan file myslist
  583.             >xeq
  584.  
  585.           If  the  file  myslist  exists it will be over-written, unless you
  586.           specify the Append option.  If you specify the append  option  the
  587.           new report will be added to the file.
  588.  
  589.           So if you want to incorporate multiple reports you just need to do
  590.           the following:
  591.  
  592.             >in test/file1sd
  593.             >list stan file myslist
  594.             >xeq
  595.             >in test/file2sd
  596.             >list stan file myslist append
  597.             >xeq
  598.  
  599.  
  600.    Enhancements in Version 4.7.10
  601.  
  602.  
  603.  
  604.    Enhancements in 4.7.10
  605.  
  606.           This version of Suprtool has some significant enhancements and are
  607.           listed below.
  608.  
  609.  
  610.    $Split Function
  611.  
  612.           Suprtool  now  allows  up  to  255 $split functions per task.  The
  613.           previous limit was 16, and the limit has been changed to assist in
  614.           reading data from "PRN" files.
  615.  
  616.  
  617.    $Edit Function
  618.  
  619.           Suprtool  can  format  fields  using edit-mask features similar to
  620.           edit-mask features of Cobol.  Suprtool employs two distinct  types
  621.           of  edit-masks: one for byte type fields and the other for numeric
  622.           fields.
  623.  
  624.           The type of mask utilized depends on the source type of the field.
  625.           If  the  source field is numeric, then the numeric edit-mask logic
  626.           is applied, if the source  field  is  byte  type,  then  the  byte
  627.           edit-mask logic and characters apply.
  628.  
  629.           The target field must always be a byte type field.
  630.  
  631.           Placeholders and Format Characters
  632.  
  633.           An edit-mask consists of "placeholder" characters, such as "9" for
  634.           a numeric column, and "format" characters, such  as  "."  for  the
  635.           decimal  place.   Sometimes  an edit-mask character acts as both a
  636.           placeholder and a format character, such as the  "$"  in  floating
  637.           dollar signs.
  638.  
  639.           Byte-Type Formatting
  640.  
  641.           For  Byte type fields there are two placeholder characters.  These
  642.           are:
  643.  
  644.             X  place the data in the  matching  column  for  the  X  in  the
  645.           edit-mask
  646.             Z   place  the  data in the matching column unless the data is a
  647.           zero; if the
  648.                data is a zero, then replace with a space
  649.  
  650.           The format characters are as follows:
  651.  
  652.             B (space) / (slash) , (comma) .  (period) + (plus) -  (minus)  *
  653.           (asterisk)  and  a Space.  Please note that you can denote a space
  654.           using two methods, either by putting a "B" in the mask or a  space
  655.           itself.
  656.  
  657.  
  658.           For  example,  suppose you have data that is in ccyymmdd format in
  659.           an X8 field.  Here is how you would use  a  "xxxx/xx/xx"  mask  to
  660.           format the data:
  661.  
  662.             >in mydate
  663.             >form
  664.                File: MYDATE.TEST.NEIL (SD Version B.00.00)
  665.                   Entry:             Offset
  666.                      A       X8      1  <CCYYMMDD>
  667.                Limit: 10000  EOF: 2  Entry Length: 8
  668.             >def formatdate,1,10
  669.             >ext formatdate=$edit(a,"xxxx/xx/xx")
  670.             >list
  671.             >xeq
  672.             >IN MYDATE.NEIL.GREEN (0) gt;OUT $NULL (0)
  673.             FORMATDATE   = 2003/09/24
  674.  
  675.             >IN MYDATE.NEIL.GREEN (1) gt;OUT $NULL (1)
  676.             FORMATDATE   = 2003/09/24
  677.  
  678.           As  you see in the example above, the placeholder character is the
  679.           "x" and the "/" is the format character.
  680.  
  681.           You insert a space either by specifying a "B"  or  by  putting  an
  682.           actual  Space character in the edit-mask.  An example of inserting
  683.           a space might be the formatting of Canadian  postal  codes  (e.g.,
  684.           V3R 7K1):
  685.  
  686.             >in postal
  687.             >form
  688.                File: POSTAL.NEIL.GREEN
  689.                   Entry:                     Offset
  690.                      POSTAL-CODE          X6      1
  691.                Limit: 10000  EOF: 2  Entry Length: 6
  692.             >def post1,1,7,byte
  693.             >def post2,1,7,byte
  694.             >ext post1=$edit(postal-code,"xxx xxx")
  695.             >ext post2=$edit(postal-code,"xxxbxxx")
  696.             >list
  697.             >xeq
  698.  
  699.             >IN POSTAL.NEIL.GREEN (0) >OUT $NULL (0)
  700.             POST1     = L2H 1L2     POST2     = L2H 1L2
  701.  
  702.             >IN POSTAL.NEIL.GREEN (1) >OUT $NULL (1)
  703.             POST1     = L2H 1L2     POST2     = L2H 1L2
  704.  
  705.           Z-placeholder for byte-fields
  706.  
  707.           The Z-placeholder character works differently for byte-fields than
  708.           for numeric fields.  For byte type fields, if  the  Z  placeholder
  709.           and  the  corresponding  data is "0", then the zero is suppressed,
  710.           regardless of the position.  This is primarily for suppression  of
  711.           zeroes in byte type date fields:
  712.  
  713.             ext a=$edit(date-field,"xxxx/zx/zx")
  714.  
  715.           The  above edit mask would then edit a byte type date of 20031005,
  716.           to be:
  717.  
  718.             2003/10/ 5
  719.  
  720.           Overflow and limits
  721.  
  722.           An edit mask is limited to 32 characters in total for both numeric
  723.           and byte type fields.  If data overflows the edit-mask, by default
  724.           Suprtool will fill that field with asterisks.  There is an  option
  725.           to have Suprtool stop when it encounters a formatting overflow:
  726.  
  727.             >set editstoperror on
  728.  
  729.           will  force  Suprtool  to  stop  if  there is data left over after
  730.           applying the edit-mask.  With byte-type fields, leading spaces  do
  731.           not cause overflow.
  732.  
  733.           Therefore if your data consists of:
  734.  
  735.             "    L2H1L2"
  736.  
  737.           and your edit mask is:
  738.  
  739.             "xxxBxxx"
  740.  
  741.           It  is  not an overflow since there are only spaces to the left of
  742.           the "L".  If the data was:
  743.  
  744.             "   JL2H1L2"
  745.  
  746.           an overflow exception would occur.
  747.  
  748.           Numeric field edit-masks
  749.  
  750.           Our edit-masks for numeric fields are  patterned  after  those  in
  751.           COBOL.   We  provide  four  placeholder  characters,  each  with a
  752.           slightly different effect:
  753.  
  754.  
  755.              "9" - insert a digit from 0 to 9 in this position
  756.  
  757.              "$" - if you specify more than  one  dollar  sign,  you  get  a
  758.           floating dollar sig
  759.              This means that there can be as many numeric positions as there
  760.           are dollar
  761.              signs, but if some positions are not needed because  the  value
  762.           is small, the $
  763.              floats  to  the right next to the first digit and the preceding
  764.           positions are
  765.              blank.
  766.  
  767.  
  768.              "*" - if there are enough digits in the value, the  *  position
  769.           is replaced
  770.              by  a  numeric  digit; if not, an asterisk is printed.  Leading
  771.           asterisks are
  772.              often used for check writing, so  that  no  one  can  insert  a
  773.           different
  774.              value.
  775.  
  776.              "z"  -  insert a numeric digit at this position; if the rest of
  777.           the data to
  778.              the left is a  zero  then  a  space  will  be  placed  at  this
  779.           position.  For example:
  780.  
  781.             >ext a=$edit(int-field,"$$,$$$.99-")
  782.             >ext b=$edit(int-field,"99,999.99-")
  783.             >ext c=$edit(int-field,"cr99999.99")
  784.             >ext d=$edit(int-field,"-$9999.99")
  785.             >ext e=$edit(int-field,"**,***.99+")
  786.             >ext f=$edit(int-field,"zz,zzz.99+")
  787.             >list
  788.             >xeq
  789.             >IN FILE1SD.NEIL.GREEN (0) >OUT $NULL (0)
  790.             A      =    $11.11-     B   = 00,011.11-
  791.             C      = CR00011.11     D   =  -$0011.11
  792.             E      = ****11.11-     F   =     11.11-
  793.  
  794.             >IN FILE1SD.NEIL.GREEN (1) >OUT $NULL (1)
  795.             A      =    $22.22-     B   = 00,022.22-
  796.             C      = CR00022.22     D   =  -$0022.22
  797.             E      = ****22.22-     F   =     22.22-
  798.  
  799.           Signs
  800.  
  801.           As  shown  in  the  example  above, there are also numerous format
  802.           characters for numeric edits, including four ways to  specify  the
  803.           sign.
  804.  
  805.           You  can  specify  a  sign,  with  +, -, or the typical accounting
  806.           specification of "CR" and "DB".  You  will  note  in  the  example
  807.           above  that  the "cr" in the mask was up-shifted to be "CR".  This
  808.           is because the entire mask is up-shifted  as  the  mask  is  being
  809.           parsed.
  810.  
  811.           You  can  specify  more  than  one  sign  in a numeric field edit,
  812.           although Suprtool will give you a warning  that  having  two  sign
  813.           edit-mask  characters  does  not  reall make sense.  Cobol gives a
  814.           Questionable warning when compiling an edit-mask with  characters.
  815.           Suprtool, will apply the sign in both places.
  816.  
  817.           Keep in mind that most data has three states:
  818.  
  819.            1) Postive
  820.            2) Negative
  821.            3) Neutral
  822.  
  823.           Any  neutral data will not display the sign.  If you specify a "+"
  824.           sign in the edit-mask and the data is negative, it will of  course
  825.           display a "-" sign.
  826.  
  827.           Decimal Places
  828.  
  829.           For  numeric-type  edits,  Suprtool  attempts  to  adjust the data
  830.           according to the number of decimal places in the  edit-mask,  when
  831.           compared to the number of decimal places defined in the field.
  832.  
  833.           For  example if the data field has one decimal place, and the edit
  834.           mask has two decimal places, then the data is adjusted:
  835.  
  836.           Data and Edit mask:
  837.  
  838.             102.3   ZZZZ.99
  839.  
  840.           will result in the final data being:
  841.  
  842.             102.30
  843.  
  844.           Similarly, if the data has three decimal places and the  edit-mask
  845.           only has two, then the data will be rounded appropriately with the
  846.           same rules as outlined in the $number function.
  847.  
  848.           You can specify more than  one  decimal  place  in  an  edit-mask.
  849.           However,  Suprtool  will  print  a warning and it will utilize the
  850.           right-most decimal place for data alignment.
  851.  
  852.           The decimal place character is defined by a set command:
  853.  
  854.              >set decimalsymbol "."
  855.  
  856.           If you define another character as the  decimal  symbol,  Suprtool
  857.           will  use  that  character as the point to align the decimals.  If
  858.           you define a decimal symbol  that  is  not  an  allowed  edit-mask
  859.           character  with  Set  Decimalsymbol, Suprtool will assume that the
  860.           field has zero decimal places and adjust the data accordingly.
  861.  
  862.           Currency and Dollar signs
  863.  
  864.           Suprtool edit-masks support both fixed and floating dollar  signs.
  865.           Logic  for  floating dollar-signs will be invoked if more than two
  866.           dollar signs are defined in the edit-mask.
  867.  
  868.           A floating-dollar edit mask attempts to put the dollar sign at the
  869.           left  most  position  of the significant data.  For example if you
  870.           have the following data and edit mask:
  871.  
  872.           0001234.54 $$$$$$.$$
  873.  
  874.           the data would end up as:
  875.  
  876.              $1234.54
  877.  
  878.           Suprtool will not however, put the dollar sign to the right of the
  879.           decimal  place.   If  you had the same edit mask and the data was,
  880.           .09, the data would end up being formatted as:
  881.  
  882.                  $.09
  883.  
  884.           Similarily, the $edit function will attempt to  place  the  dollar
  885.           sign  correctly  in  most  cases.   For  example Suprtool will not
  886.           format data in the form of:
  887.  
  888.              $,123.50
  889.  
  890.           Suprtool, does attempt to fixup these cases and would  format  the
  891.           data in the following manner:
  892.  
  893.               $123.50
  894.  
  895.           Overflow and floating dollars
  896.  
  897.           If  the  number  of  digits  in the data is equal to the number of
  898.           placeholder dollar signs, then the dollar sign is dropped and  not
  899.           added to the edited field.
  900.  
  901.           12345.50 $$$$$.99
  902.  
  903.           would result in:
  904.  
  905.           12345.50
  906.  
  907.           Set CurrencySymbol
  908.  
  909.           If  Set  CurrencySymbol  is  not  equal  to  "$",  then  after the
  910.           formatting has been applied, whatever symbol(s) are defined within
  911.           the set command, are used to replace the "$" symbol in the data.
  912.  
  913.           For example, if you have the Currency symbol set as "CDN".
  914.  
  915.             >set currencysymbol "CDN"
  916.  
  917.           Suprtool will replace the "$" after the edit-mask has been applied
  918.           with CDN, provided there is room to the left of the dollar-sign.
  919.  
  920.           It is recommended that if you are using  multiple  characters  for
  921.           the  dollar symbol that you leave enough characters to the left of
  922.           the symbol.
  923.  
  924.           For example if the CurrencySymbol is  defined  as  CDN,  then  you
  925.           should  leave  two  spaces  to  the  left  of  a fixed dollar sign
  926.           definition.  If there is not enough room, to put in  the  currency
  927.           symbol, then the dollar symbol is blank.
  928.  
  929.           Overflow and limits
  930.  
  931.           An edit mask is limited to 32 characters in total for both numeric
  932.           and byte type fields.  If data overflows the edit-mask, by default
  933.           Suprtool  will fill that field with asterisks.  There is an option
  934.           to have Suprtool stop when it encounters a formatting overflow:
  935.  
  936.             >set editstoperror on
  937.  
  938.           will force Suprtool to stop if there is data left  over  to  place
  939.           when  applying  the  edit-mask.  With numeric-type fields, leading
  940.           zeroes do not cause overflow.
  941.  
  942.  
  943.    Oracle Open
  944.  
  945.           The Open command has been  enhanced  to  allow  connections  to  a
  946.           remote  oracle  database.   In  order  to  invoke this feature the
  947.           username/password machine, need to be specified on a single line.
  948.  
  949.             >open oracle suprtest/suprpass@remote
  950.  
  951.           There are some issues with using this syntax, for more information
  952.           please read the section entitle Known Problems.
  953.  
  954.  
  955.  
  956.  
  957.  
  958.    Bugs Fixed in Version 4.8.02
  959.  
  960.              Chain  Command.   The  information  about  the data loaded in a
  961.              Table would be lost if  the  table  being  referenced  was  the
  962.              second  held  table  and  the  previous task involved the Chain
  963.              command.
  964.  
  965.              Get Command.  The Get command would not get correct end of file
  966.              signal  if  the  dataset  was empty and being accessed with Set
  967.              FastRead On.
  968.  
  969.  
  970.    Bugs Fixed in Version 4.8.01
  971.  
  972.           Chain command.   The chain command does  not  return  the  correct
  973.           record with Set FastRead On.
  974.  
  975.  
  976.    Bugs Fixed in Version 4.8
  977.  
  978.           $Edit  Function.    The $edit function now returns a proper result
  979.           when nested within another string function such as $ltrim.
  980.  
  981.           Clean Command.   The clean command was improperly upshifting lower
  982.           case alpha characters.
  983.  
  984.  
  985.    Bugs Fixed in Version 4.7.12
  986.  
  987.           $SubTotal  Function.   The $subtotal function would cause Suprtool
  988.           to fail if the size of the  Output  buffer  was  larger  than  the
  989.           record input.
  990.  
  991.  
  992.    Bugs Fixed in Version 4.7.11
  993.  
  994.           Variable Substitution.   Suprtool would report the error:
  995.  
  996.              Error:  >KEY has 2-4 parms: pos,len[,type][,DESC].
  997.  
  998.           when  resolving a variable that resolved to a blank line.  This is
  999.           now fixed in Suprtool 4.7.11.
  1000.  
  1001.           $Total Function.   The $total function would appear to  accumulate
  1002.           incorrectly when sorting in the same task.
  1003.  
  1004.           $SubTotal Function.   The $subtotal function would not work if run
  1005.           in the same copy  of  Suprtool  if  the  previous  task  used  the
  1006.           Duplicate command.
  1007.  
  1008.           $SubTotal  Function.    The  $subtotal  function  would  not  work
  1009.           randomly due to an un-initialized variable.
  1010.  
  1011.  
  1012.    Bugs Fixed in Version 4.7.10
  1013.  
  1014.           Eloquence  and  Form  command.    The  Form  command  would   show
  1015.           percentage full as a very large strange number if the capacity and
  1016.           entries were both zero for a given Eloquence database.
  1017.  
  1018.           Eloquence and Update Ciupdate.   An  Update  on  a  Critical  Item
  1019.           would  not  work  if  the  CIUPDATE  flag  status for an Eloquence
  1020.           database was only Allowed.  The flag needed to be enabled  for  an
  1021.           Update Ciupdate operation to work.
  1022.  
  1023.           Incorrect  Flimit.    Suprtool  would  incorrectly  calculate  the
  1024.           flimit on an output file when using Numrecs 100%, and if the input
  1025.           file was very large.
  1026.  
  1027.           $Split  generating  random  characters.    The new $split function
  1028.           would put random characters at the point  where  the  split  would
  1029.           occur in some cases.
  1030.  
  1031.           $Split  reported  bogus  error  on repeated task.   The new $split
  1032.           function would incorrectly report an error in a second  task  with
  1033.           multiple $split operations.
  1034.  
  1035.           $Number decimal only numbers incorrect.   The new $number function
  1036.           did not handle numbers that consisted  of  only  a  decimal  place
  1037.           followed by any number of zeroes and a number, as in .01 thru .09.
  1038.  
  1039.           Empty Join File caused abort.   Suprlink would abort if  the  Join
  1040.           file was empty.
  1041.  
  1042.           Join  File  held  open.   Suprlink would hold the Output file open
  1043.           after the task was completed.
  1044.  
  1045.           $Subtotal incorrect.   Suprtool would give incorrect numbers for a
  1046.           $subtotal function in certain cases.
  1047.  
  1048.           Percentage  Full  on Form command.   The form command would report
  1049.           an incorrect Percentage full if the capacity and entries were both
  1050.           zero.
  1051.  
  1052.           Oracle  Open.    With  Oracle  9.2.0.2  and  Interim Patch 2713497
  1053.           installed, the Suprtool Open command could no  longer  connect  to
  1054.           Oracle databases.  An Open command would fail with:
  1055.  
  1056.               >open Oracle suprtest suprpass
  1057.               Error:  Unable to connect to the Oracle database
  1058.               Error:  ORA-01017: invalid username/password; logon denied
  1059.  
  1060.           we  have  made  changes to fix this problem by calling a different
  1061.           Oracle Call Interface call.  In order to invoke  this  other  call
  1062.           you can use the set command of:
  1063.  
  1064.             >set oracle openfix on
  1065.  
  1066.           There  are  two  issues  outstanding  with  this  fix,  which  are
  1067.           documented in the Known Problems section.
  1068.  
  1069.  
  1070.  
  1071.    Bugs Fixed in Version 4.7.02
  1072.  
  1073.  
  1074.    Bogus Error with $number.   Suprtool would incorrectly  report  an  error
  1075.           when using the $number function in some cases.
  1076.  
  1077.  
  1078.    Incorrect  Flimit on Output file.   Suprlink and STExport would build the
  1079.           output file with an incorrect flimit.
  1080.  
  1081.  
  1082.    Bugs Fixed in Version 4.7.01
  1083.  
  1084.  
  1085.    DbLogon Error.   The base command would fail with a dblogon error message
  1086.           if security on an Eloquence database was setup a certain way.
  1087.  
  1088.  
  1089.  
  1090.    Enhancements in Version 4.7
  1091.  
  1092.  
  1093.  
  1094.    $Number Function if and Extract
  1095.  
  1096.           Suprtool  now  has  the  ability  to accept free-form "numbers" as
  1097.           display data types.  This means number in the form:
  1098.  
  1099.            1234.45-
  1100.            -12345
  1101.            -123.2134
  1102.             12343
  1103.  
  1104.           can now be accepted and converted to any other numeric data type.
  1105.  
  1106.           Consider the following data:
  1107.  
  1108.            Item-number    New-Price
  1109.             12345          +123.45
  1110.             34563          + 27.5
  1111.             21312          +  1.545
  1112.  
  1113.           Suprtool can now read and convert the data in New-Price using  the
  1114.           number  function.   Let's  say  we  want  New-Price to be a double
  1115.           integer and currently occupies eight bytes  starting  in  position
  1116.           six.
  1117.  
  1118.           Here   is  the  task  you  would  use  to  convert  the  New-Price
  1119.           free-format number into a double integer.
  1120.  
  1121.             >in mynums
  1122.             >def item-number,1,5,byte
  1123.             >def new-price-ascii,6,8,display
  1124.             >def new-price,1,4,double
  1125.             >item new-price-ascii,dec,2
  1126.             >item new-price,dec,2
  1127.             >ext item-number
  1128.             >ext new-price=$number(new-price-ascii)
  1129.             >out somefile,link
  1130.             >xeq
  1131.  
  1132.           The $number function take the free-format number  and  make  it  a
  1133.           valid display number.  It will determine the decimal, sign and add
  1134.           leading zeroes.  It will round the number to the defined number of
  1135.           decimal places.
  1136.  
  1137.           In  the  case of 1.545 number, Suprtool will round the value to be
  1138.           1.55, since the given number of decimal  places  is  two  and  the
  1139.           preceding  value  is  five or greater.  If you have a whole number
  1140.           such as 54, with no decimal point the value becomes 54.00.
  1141.  
  1142.           Suprtool will not accept data that has:
  1143.  
  1144.              More than one sign.
  1145.              More than one decimal place.
  1146.              Spaces in between numbers.
  1147.              Signs that are in between numbers.
  1148.              Characters that are not over punch characters.
  1149.              Fields that when edited do not fit in the defined space for the
  1150.           display field
  1151.  
  1152.           You  can control the character that defines the currency, thousand
  1153.           and decimal symbol for other  currencies  and  formats  using  the
  1154.           following commands:
  1155.  
  1156.              >set decimalsymbol "."
  1157.              >set thousandsymbol ","
  1158.              >set currencysymbol "$"
  1159.  
  1160.           Suprtool  in  the  above case will strip the currency and thousand
  1161.           symbols and use the decimal symbol  to  determine  the  number  of
  1162.           decimal  places.   You  can set these characters to any values you
  1163.           want but the defaults for each are used in the above set commands.
  1164.  
  1165.           The  Decimal and thousand symbols are only single characters.  The
  1166.           currency symbol allows for four characters.
  1167.  
  1168.  
  1169.  
  1170.    Suprlink Many-to-Many Link
  1171.  
  1172.  
  1173.           Suprlink can now  join  files  together  that  have  multiple  key
  1174.           records  in  each  file,  what  has  been  come  to  be  know as a
  1175.           many-to-many link.  Suprlink has traditionally been able  to  link
  1176.           an  Input  file with many records with the same key to a Link file
  1177.           that has a single record with the same key value.
  1178.  
  1179.           The Join command, will now link two files with many key records in
  1180.           both the inpu and the "Linking" file.
  1181.  
  1182.           The  syntax  of  the  Join command is exactly the same as the Link
  1183.           command so a sample task would look as follows:
  1184.  
  1185.              +input ordhist
  1186.              +join  orders
  1187.              +output custord
  1188.              +xeq
  1189.  
  1190.           The above task will link multiple records of the file ordhist,  to
  1191.           the multiple records of the file in orders.  This assumes that the
  1192.           files are sorted by a common key.  In SQL terms this is  known  as
  1193.           an Inner Join.
  1194.  
  1195.           An  Outer Join, one where the keys do not necessarily have a match
  1196.           can be achieved  by  adding  the  optional  keyword  to  the  Join
  1197.           command:
  1198.  
  1199.              +input ordhist
  1200.              +join  orders optional
  1201.              +output joined
  1202.              +xeq
  1203.  
  1204.           In SQL parlance, once again you can achieve both a Left Outer Join
  1205.           and Right Outer Join by reversing the order of the files,  between
  1206.           the input and the join commands.
  1207.  
  1208.           To  give  you  an  example  of  how  the Join operation would work
  1209.           consider the following data.  First we have an inventory file with
  1210.           multiple  records for the same product-no.  This data is stored in
  1211.           the file dinv:
  1212.  
  1213.              50512001  {Rest of data}
  1214.              50512001  {Rest of data}
  1215.              50512003  {Rest of data}
  1216.  
  1217.           The next file will have sales records, once  again  with  multiple
  1218.           key values, this data is stored in the file dsales:
  1219.  
  1220.              50512001  {Rest of data}
  1221.              50512001  {Rest of data}
  1222.  
  1223.           If  you  did  the following task assuming both files are sorted by
  1224.           the product-no:
  1225.  
  1226.             +in dinv
  1227.             +join dsales
  1228.             +out invsales
  1229.             +xeq
  1230.  
  1231.           The resulting file would have  four  records,  with  the  multiple
  1232.           matching  dinv  and  dsales records.  The record layout would have
  1233.           the dinv information first followed by the dsales information.
  1234.  
  1235.           If you add the optional keyword on the join command the  resulting
  1236.           file  would  have 5 records.  The matching 4 records from dinv and
  1237.           dsales as well as the dinv record that  did  not  match  with  the
  1238.           numeric fields set to zero and the byte fields set to spaces.
  1239.  
  1240.           Only one Join operation is allowed per task.
  1241.  
  1242.           By  default,  Suprlink  will join files base on the primary sorted
  1243.           key in the self-describing file.  You can specify a secondary  key
  1244.           for  the files to be joined on in a similar manner to how the Link
  1245.           command did:
  1246.  
  1247.             +in orders
  1248.             +join dsales by order-no product-no
  1249.             +out ordsales
  1250.             +xeq
  1251.  
  1252.  
  1253.    Splitting Byte Fields
  1254.  
  1255.           Suprtool can extract  portions  of  a  byte  field  based  on  the
  1256.           occurrence of certain characters.
  1257.  
  1258.           Consider the following Data:
  1259.  
  1260.             Armstrong/ Neil/ Patrick
  1261.             Green/ Bob/ Miller
  1262.             Fritshaw/ Elizabeth/
  1263.             Edwards/ Janine/
  1264.             Armstrong/Arthur/Derek
  1265.  
  1266.           The  $split  function can extract each token into separate fields.
  1267.           The syntax for the $split function is:
  1268.  
  1269.              $split(Field,StartCharacter,occurrence,EndCharacter,occurrence)
  1270.  
  1271.           The  following  task  will  $split the data in the wholefield into
  1272.           three separate fields.
  1273.  
  1274.             >in namefile
  1275.             >define lastname,1,30
  1276.             >define firstname,1,20
  1277.             >define middlename,1,20
  1278.             >extract lastname = $split(wholename,first,"/")
  1279.             >extract firstname=$trim($split(wholename,"/","/"))
  1280.             >extract middlename=$trim($split(wholename,"/",2," ",2))
  1281.             >out names,link
  1282.             >xeq
  1283.  
  1284.           The first extract statement tells Suprtool extract the bytes  from
  1285.           the  field  wholename,  starting at the beginning (first keyword),
  1286.           and stopping at the "/" character.
  1287.  
  1288.           The second extract statement, tells Suprtool to extract the  bytes
  1289.           between  the  first  occurrence  of  the "/" character to the next
  1290.           occurrence of the "/" character, and then that string  is  trimmed
  1291.           of spaces as it is nested within the $trim function.
  1292.  
  1293.           The  third  and  final extract statement tells Suprtool to extract
  1294.           the bytes beginning with the second occurence of the "/" character
  1295.           to the second occurrence of the space character.
  1296.  
  1297.           If  the  target field is not long enough to hold the data Suprtool
  1298.           will abort with an  error.   You  can  easily  prevent  this  from
  1299.           happening on blank fields by nesting the $split statement within a
  1300.           $trim or $rtrim function.
  1301.  
  1302.           The $split function also has a Last keyword, whereby you can split
  1303.           the field from a given occurrence of a character to the end of the
  1304.           field.
  1305.  
  1306.           So in the given example from  above  the  extracting  out  of  the
  1307.           middlename could be coded as such:
  1308.  
  1309.             >extract middlename=$trim($split(wholename,"/",2,last))
  1310.  
  1311.           The  above  means  to  extract  out  all  the data from the second
  1312.           occurrence of the "/", to the  end  of  the  field  and  trim  all
  1313.           spaces.
  1314.  
  1315.  
  1316.  
  1317.    Control Break Totals
  1318.  
  1319.           Suprtool  now  has  the ability to keep a running subtotal for any
  1320.           numeric field based on a given sort key.
  1321.  
  1322.           The target data must be a packed field with 28 digits, in order to
  1323.           help avoid overflow issues.
  1324.  
  1325.           A sample use of the $subtotal function could be:
  1326.  
  1327.             >def mytotal,1,14,packed
  1328.             >get orders
  1329.             >sort order-number
  1330.             >ext order-number
  1331.             >ext part-number
  1332.             >ext description
  1333.             >ext sales-amount
  1334.             >ext mytotal = $subtotal(sales-amount,order-number)
  1335.             >out sales,link
  1336.             >xeq
  1337.  
  1338.           This  would  result in a file containing a running subtotal in the
  1339.           field mytotal f order-number.  You could then  generate  a  simple
  1340.           report with the simple Suprtool c
  1341.  
  1342.             >in sales
  1343.             >list standard
  1344.             >xeq
  1345.  
  1346.           The basic syntax for the $subtotal function in the extract command
  1347.           is:
  1348.  
  1349.             extract targetfield = $subtotal(field,sort-field)
  1350.  
  1351.           You  must  specify  the  sort  command  before   referencing   the
  1352.           sort-field in the $subtotal function.
  1353.  
  1354.           You  can  subtotal  up  to  ten  fields per pass and the $subtotal
  1355.           function is also available in  the  if  command,  however,  is  of
  1356.           limited use.
  1357.  
  1358.  
  1359.    Clean Command Syntax
  1360.  
  1361.           The  Clean command has improved syntax to specify which characters
  1362.           to look to replace.  You can specify special characters Decimal  0
  1363.           thru Decimal 31 via the command:
  1364.  
  1365.             Clean special
  1366.  
  1367.           You  can also specify a range or characters by using the following
  1368.           syntax:
  1369.  
  1370.             Clean "^0:^31","^240:^255"
  1371.  
  1372.           This enhancement makes it much  easier  to  define  characters  to
  1373.           search  for  and  Clean.   This  is available in both Suprtool and
  1374.           STExport.
  1375.  
  1376.  
  1377.    Outcount information
  1378.  
  1379.           Suprlink and STExport on HP-UX now have a method for reporting how
  1380.           many  records  have been output.  In Suprtool, we wrote the number
  1381.           of records to a file called .stoutcount.  In Suprlink and STExport
  1382.           we used the files, .sloutcount and .sxoutcount respectively.
  1383.  
  1384.           For Suprlink:
  1385.  
  1386.                #!/bin/sh
  1387.                #
  1388.  
  1389.                suprlink -oc << !EOD
  1390.                +in orders
  1391.                +join ordhist
  1392.                +out ordcomb
  1393.                exit
  1394.                !EOD
  1395.                if [ `cat .sloutcount` -ge 10 ]; then
  1396.                   echo "More than 10 records found"
  1397.                fi
  1398.  
  1399.           For STExport:
  1400.  
  1401.                #!/bin/sh
  1402.                #
  1403.  
  1404.                stexport -oc << !EOD
  1405.                $in orders
  1406.                $heading fieldnames
  1407.                $out ordprn
  1408.                exit
  1409.                !EOD
  1410.                if [ `cat .sxoutcount` -ge 10 ]; then
  1411.                   echo "More than 10 records found"
  1412.                fi
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.    HP Eloquence 7
  1419.  
  1420.           Suprtool  has  been  enhanced  to  be  compatible and work with HP
  1421.           Eloquence version Seven.  It takes advantage of many new  features
  1422.           and supports the new limits and data types.
  1423.  
  1424.  
  1425.    Base Command
  1426.  
  1427.           Suprtool's  Base command has been enhanced to allow the new syntax
  1428.           supported  in  HP  Eloquence  7.   HP  Eloquence  now  allows  the
  1429.           servername and service to be specified in dbopen.  To support this
  1430.           new syntax Suprtool's Base command has been changed to  allow  the
  1431.           servername, service and database name be specified.  Suprtool uses
  1432.           the same syntax as HP Eloquence whereby the database name consists
  1433.           of the following elements:
  1434.  
  1435.             [[host][:service]/]database
  1436.  
  1437.           Examples  of  using  this  syntax within Suprtool using the sample
  1438.           database that HP Eloquence provides.:
  1439.  
  1440.             base sample,5
  1441.             base :eloqdb/sample,5
  1442.             base hostname.robelle.com:eloqdb/sample,5
  1443.  
  1444.  
  1445.  
  1446.    Put Command
  1447.  
  1448.           The Put command has always supported for a  database  name  to  be
  1449.           specified.   Since  the  Base command allows the new syntax for HP
  1450.           Eloquence version 7 support, the Put command also allows this  new
  1451.           syntax.
  1452.  
  1453.             put dataset,sample
  1454.             put dataset,:eloqdb/sample
  1455.             put dataset,hostname.robelle.com:eloqdb/sample
  1456.  
  1457.  
  1458.    Expanded Database Limits
  1459.  
  1460.           HP  Eloquence version 7 now has new database limits that follow or
  1461.           extend the current Turbo IMAGE limits.
  1462.  
  1463.             Data Items per database       2048
  1464.             Data Sets per database        500
  1465.             Paths per dataset detail      16
  1466.             Paths per dataset master      64
  1467.  
  1468.  
  1469.  
  1470.    Cleaning your Data
  1471.  
  1472.           In this day and age of migrations we were looking at  issues  that
  1473.           customers  have  run  into when importing data into new databases.
  1474.           What came from this investigation where ways to Clean up your data
  1475.           in any given byte type field.
  1476.  
  1477.           We have added two methods to clean your data, you can use Suprtool
  1478.           to clean an individual byte type field, or STExport to  clean  all
  1479.           of the byte-type fields for a given file that you are exporting.
  1480.  
  1481.  
  1482.    Suprtool
  1483.  
  1484.           Sometimes  un-printable  or  extraneous  characters  get stored in
  1485.           files or databases that have no business being there.  This may be
  1486.           some  tab  characters  in an address field or perhaps and embedded
  1487.           carriage return or line-feed.
  1488.  
  1489.           Suprtool now  supports  the  clean  function  which  will  replace
  1490.           individual characters for a given byte field.
  1491.  
  1492.           There  are  three  things  that Suprtool needs to know in order to
  1493.           "clean" a field.  Suprtool needs to know which characters it needs
  1494.           to  clean,  what character it needs to change the "bad" characters
  1495.           to, and also what field does it need to clean.
  1496.  
  1497.  
  1498.    Defining a Clean Character
  1499.  
  1500.           The Clean command is used to  tell  Suprtool  what  characters  it
  1501.           needs to look for in a given byte type field.  For example:
  1502.  
  1503.               clean "^9","^10","."
  1504.  
  1505.           will  tell Suprtool to replace the tab character (Decimal 9), Line
  1506.           Feed (Decimal 10), and a period to whatever the Clean character is
  1507.           set to.
  1508.  
  1509.           The  CLean  command takes both, decimal notation and the character
  1510.           itself, however, it is probably most convenient to use the Decimal
  1511.           notation  for  the characters that you wish to clean.  The Decimal
  1512.           notation is indicated by the "^" character.
  1513.  
  1514.  
  1515.    Setting the Clean Character
  1516.  
  1517.           By default, Suprtool will replace any of the characters  specified
  1518.           in the clean command with a space.  You can specify what character
  1519.           to use to replace any of the  characters  that  qualify  with  the
  1520.           following set command:
  1521.  
  1522.              >set CleanChar "."
  1523.  
  1524.           This  will  set the character to replace any of the qualifying "to
  1525.           be cleaned" characters to be a period.
  1526.  
  1527.  
  1528.    Cleaning a Field
  1529.  
  1530.           You call the clean function, the same way you normally  use  other
  1531.           functions available to if and extract.  For example:
  1532.  
  1533.              ext address1=$clean(address1)
  1534.  
  1535.           shows  how  to  clean  the field address1.  You do not necessarily
  1536.           need to have the target field be the same as the source field.
  1537.  
  1538.             def new-address,1,30
  1539.             ext new-address=$clean(address1)
  1540.  
  1541.  
  1542.    Cleaning your data
  1543.  
  1544.           An example of how easy it would  be  to  clean  your  database  of
  1545.           certain "bad" characters in byte-type fields would be as follows:
  1546.  
  1547.                >base mydb,1,;
  1548.                >get customer
  1549.                >clean "^9","^10","^0","^7"
  1550.                >set cleanchar " "
  1551.                >update
  1552.                >ext address(1) = $clean(address(1))
  1553.                >ext address(2) = $clean(address(2))
  1554.                >ext address(3) = $clean(address(3))
  1555.                >xeq
  1556.  
  1557.           The  above  task  will  look at the three instances of address and
  1558.           replace the tab, linefeed, null and bell characters with a space.
  1559.  
  1560.  
  1561.    STExport
  1562.  
  1563.           This same feature has been added to STExport, except that STExport
  1564.           will  automati clean all the byte type fields for a given SD file.
  1565.           The commands are very simila STExport just needs to know what  the
  1566.           replace character should be and what charac needs to look for.
  1567.  
  1568.              $ in mysdfile
  1569.              $clean "^9","^10","^0","^7"
  1570.              $set cleanchar " "
  1571.              $out myexport
  1572.              $xeq
  1573.  
  1574.           Since  the  Cleanchar  is  by default set to space, the above task
  1575.           could simply be:
  1576.  
  1577.              $in mysdfile
  1578.              $clean "^9","^10","^0","^7"
  1579.              $out myexport
  1580.              $xeq
  1581.  
  1582.  
  1583.    Escape Command
  1584.  
  1585.           Many SQL importers allow you to add an escape character  in  front
  1586.           of characters that may mean something else to the import program.
  1587.  
  1588.           For  example  if  the  import  program  thinks  that the delimiter
  1589.           character is a comma, the importer may treat a comma in an address
  1590.           field as an indication to move to the next field, which will throw
  1591.           of the import.
  1592.  
  1593.           Some import programs, will treat the next  character  as  data  as
  1594.           opposed  to  a delimeter if the character is preceded by an escape
  1595.           character, such as a slash.
  1596.  
  1597.           Thus when  the  field  is  analyzed  by  STExport  the  data  that
  1598.           originally started as:
  1599.  
  1600.              "Niagara Falls,Ontario, Canada"
  1601.  
  1602.           would be transformed to be:
  1603.  
  1604.             "Niagara Falls/,Ontario/, Canada"
  1605.  
  1606.           This  function  will  not work on fixed columns and can be invoked
  1607.           with the escape command:
  1608.  
  1609.              escape delimeter quote eol "/"
  1610.  
  1611.           The above command will take the defined delimeter, quote  and  Eol
  1612.           and escape with a "/", if found  in any byte type field.
  1613.  
  1614.  
  1615.    Table Command filename
  1616.  
  1617.  
  1618.           Previously  the  permitted  length  for the filename for the Table
  1619.           command  was  36  characters.   This  has  been  increased  to  80
  1620.           characters.
  1621.  
  1622.  
  1623.  
  1624.    Running Totals
  1625.  
  1626.           Suprtool  now  has  the  ability  to  keep a running total for any
  1627.           numeric field.  The target data must be a  packed  field  with  28
  1628.           digits, in order to help avoid overflow issues.
  1629.  
  1630.           A sample use of the total function could be:
  1631.  
  1632.             >def mytotal,1,14,packed
  1633.             >get orders
  1634.             >ext mytotal = $total(sales-amount)
  1635.             >xeq
  1636.  
  1637.           You can total up to ten fields per pass and the $total function is
  1638.           also available in the if command, however, is of limited use.
  1639.  
  1640.  
  1641.    $Counter Function
  1642.  
  1643.           For years Suprtool has had the ability to output a  record  number
  1644.           to an output file with the num option of the output command:
  1645.  
  1646.             >in mysdfile
  1647.             >out myfile,num,data
  1648.  
  1649.           The  above  could  would  generate  an  output file called myfile,
  1650.           however, you would the SD information and you  can  only  put  the
  1651.           number  at  the  beginning  or the end o data.  Suprtool now has a
  1652.           counter function that allows you to place a $counter  at  spot  as
  1653.           well as preserve the SD information.
  1654.  
  1655.             >in mysdfile
  1656.             >def mycount,1,4,double
  1657.             >ext field1
  1658.             >ext field2
  1659.             >ext mycount=$counter
  1660.             >out myfile,link
  1661.             >xeq
  1662.  
  1663.           The  file  myfile  will  be self-describing and contain the fields
  1664.           field1, field2 an mycount.  The field  mycount  is  defined  as  a
  1665.           double integer, since this is the onl field type that the $counter
  1666.           function can use.  Each record will have a unique ascending number
  1667.           starting with one.
  1668.  
  1669.  
  1670.  
  1671.    Variable Substitution
  1672.  
  1673.           Suprtool  for  HP-UX  4.6.02  now  supports  environment  variable
  1674.           substitution.  To use this enhancement you must do a:
  1675.  
  1676.             >set varsub on
  1677.  
  1678.           Due to how HP-UX processes work  with  environment  variables  any
  1679.           variables  must be exported prior to running Suprtool, STExport or
  1680.           Suprlink.
  1681.  
  1682.           All of these modules support HP-UX variable Substitution.
  1683.  
  1684.              export tablefile='abcdefghijklmnopqrstuvwxyzabcd'
  1685.              export infile='file1sd'
  1686.              ./suprtool -oc << !EOD
  1687.               set varsub on
  1688.               in $infile
  1689.               table mytable,char-field,file, &
  1690.                  /users/robdev/suprtool/test/$tablefile
  1691.               if $lookup(mytable,char-field)
  1692.               out file05,link
  1693.               exit
  1694.               !EOD
  1695.  
  1696.  
  1697.           Suprtool examines a command line and looks for  variables  denoted
  1698.           by  the  "$"  sign.   Since Suprtool has some functions that begin
  1699.           with a $-sign, these will take precedence regardless of the  value
  1700.           set in the variable.
  1701.  
  1702.  
  1703.    Tables on HP-UX Improvements
  1704.  
  1705.           We  have  re-written  the  underlying mechanisms for the Table and
  1706.           $Lookup functions in Suprtool for HP-UX, to allow more data in the
  1707.           table  and have similar functionality to the Table command on MPE.
  1708.           This includes Larger tables and Extract from a table functionality
  1709.           described below.
  1710.  
  1711.  
  1712.    Table Sizes
  1713.  
  1714.           On  HP-UX  you can control the size of a table with the Set Limits
  1715.           TableSize command.  By default an  individual  Table  will  be  50
  1716.           Megabytes  in  size  and you can have up to 10 tables.  The Global
  1717.           limit for all tables is up to 500 Megabytes.  You can control  the
  1718.           size of a given table with the command:
  1719.  
  1720.            >Set Limits TableSize n
  1721.  
  1722.           If  you  enter  the  command Set Limits TableSize 100 and the next
  1723.           table command that you build will have a limit of 100 Megabytes.
  1724.  
  1725.           Previously the Limits on Tables were 15Mb in total  and  defaulted
  1726.           to 1Mb in size.
  1727.  
  1728.  
  1729.  
  1730.    Extract from a Table
  1731.  
  1732.           Suprtool  now  has  the  ability to load data into a table via the
  1733.           Table command, and extract that data out of the  table  using  the
  1734.           Extract command.
  1735.  
  1736.           The  Table  command  now  allows  for data to be loaded along with
  1737.           matching key values.
  1738.  
  1739.              >table table-name,key-field,file,filename,&
  1740.               data(field1,field2,...)
  1741.  
  1742.           An example of loading two data fields called cost and  desc  along
  1743.           with the key field of part into a table would be:
  1744.  
  1745.              >table partab,part,file,partin,data(cost,desc)
  1746.  
  1747.           You  can specify up to 20 data fields as long as the total size of
  1748.           the key fields and data does not exceed 256 bytes.  The Table file
  1749.           must be Self-Describing (Link) in order to use the data option.
  1750.  
  1751.           When  loading  data  into  a  table,  Suprtool  will eliminate the
  1752.           duplicate entries based on the key value, so the  associated  data
  1753.           values may not be loaded into the table.
  1754.  
  1755.           The  Extract  command  can  utilize the $lookup function to return
  1756.           data.  The syntax for the $lookup function would look as follows:
  1757.  
  1758.            >extract target = $lookup(table-name,key-field,data-field)
  1759.  
  1760.           The Table name, key-field and data-field are all  defined  by  the
  1761.           Table command, which must be input before the Extract command.
  1762.  
  1763.           A  classic  example:  your  boss  comes  to you with a list of new
  1764.           prices and descriptions for certain  parts  for  your  Part-Master
  1765.           dataset.
  1766.  
  1767.           The  basic  steps  to  do  this  are  to  load  the new prices and
  1768.           descriptions into a Table, index by the product  number  (prodno),
  1769.           then  Extract the price field from each record and replace it with
  1770.           a $lookup on the table.
  1771.  
  1772.           Here is the Suprtool code:
  1773.  
  1774.            >table newprices,prodno,file,bosslist,data(price,desc)
  1775.            >get part-master
  1776.            >if $lookup(newprices,prodno)
  1777.            >update
  1778.            >extract price = $lookup(newprices,prodno,price)
  1779.            >extract desc = $lookup(newprices,prodno,desc)
  1780.            >xeq
  1781.  
  1782.           We do the If $lookup to select  only  the  parts  which  have  new
  1783.           prices, then do Extract with $lookup to replace the existing price
  1784.           with a new one.  The Update command forces a  database  update  on
  1785.           each selected record and must come before the Extract command.
  1786.  
  1787.           If  you  did not specify the If $lookup, then records that did not
  1788.           qualify under the $lookup function  in  the  extract  field,  will
  1789.           result  in  zeroes  for  any numeric field and spaces for any byte
  1790.           type fields.
  1791.  
  1792.  
  1793.  
  1794.  
  1795.    Bugs Fixed in Version 4.6.04
  1796.  
  1797.  
  1798.  
  1799.    Incorrect record Number.   Suprtool would incorrectly report  the  record
  1800.           number  when an Illegal Ascii digit was encountered on a Duplicate
  1801.           operation.  We no longer attempt to show the  record  number  from
  1802.           the Input source.
  1803.  
  1804.  
  1805.    Set Limits  Tablesize.    Suprtool  would report an error on a second Set
  1806.           Limits TableSize command if the value given was  larger  than  the
  1807.           previous.
  1808.  
  1809.  
  1810.    Bugs Fixed in Version 4.6.03
  1811.  
  1812.  
  1813.    Extract from  a  Table.    Suprtool  would incorrectly report an error in
  1814.           some cases when doing an update from a table.   The  error  "Field
  1815.           offset  is  beyond the input record length" was incorrectly hit if
  1816.           the input file was smaller than the actual  length  of  the  table
  1817.           file.
  1818.  
  1819.  
  1820.  
  1821.    $Counter  Function.    Suprtool  did  not  correctly  reset  the $counter
  1822.           variable in between tasks.
  1823.  
  1824.  
  1825.    Bugs Fixed in Version 4.6.02
  1826.  
  1827.  
  1828.    Define Commands.    The  number  of  Define  commands  allowed  has  been
  1829.           increased  to  768 defines.  The number of defines allowed used to
  1830.           be a variable number dependant on various  system  settings,  this
  1831.           was changed in Suprtool 4.4.10 to be a fixed structure.
  1832.  
  1833.  
  1834.    Bugs Fixed in Version 4.6.01
  1835.  
  1836.  
  1837.    Packed and  Display  Coercion.    Suprtool would incorrectly coerce large
  1838.           negative numbers from one Packed or Display field.
  1839.  
  1840.  
  1841.    Input Filename (start/end).   Suprtool would  fail  with  prefetch  point
  1842.           failure  if  the  file  had  an  uneven  record size and an uneven
  1843.           blocking factor.
  1844.  
  1845.  
  1846.    HTML and XML commands.   STExport  now  properly  converts  the  Roman  8
  1847.           universal  monetary  symbol to the Euro-Symbol in the HTML and XML
  1848.           commands.
  1849.  
  1850.           The XML command would fail to convert ">"  to  ">"  and  "<"  to
  1851.           "<".
  1852.  
  1853.           The XML and HTML commands failed to convert "&" to "amp".
  1854.